feat: Support SQL Struct/JSON field access operators

[alexander-beedie]

Builds on #17109, which added support for querying into Struct fields using dot-notation.

This PR extends that by adding the PostgreSQL operator equivalents¹.
Can use for both array and field indexing.

• -> Extract value at key/index.
• ->> Extract value at key/index as a string.
• #> Extract value at specified path, where path elements can be keys or indexes.
• #>> Extract value at specified path, where path elements can be keys or indexes, as a string.

Note

Unlike standard array-indexing in PostgreSQL, which is 1-indexed, these operators expect 0-indexing as they follow JSON conventions, so the following two queries are equivalent (and both now parse):

• df.sql('SELECT nested."0"[1] FROM self')
• df.sql("SELECT nested -> '0' -> 0 FROM self")

"Yay for consistency within SQL statements" 🙄

Examples

import polars as pl

df = pl.DataFrame({
    "nested": {
        "0": ["baz"],
        "b": ["foo", "bar"],
        "c": [3, 2, 1],
    },
})
# shape: (1, 1)
# ┌────────────────────────────────────┐
# │ nested                             │
# │ ---                                │
# │ struct[3]                          │
# ╞════════════════════════════════════╡
# │ {["baz"],["foo", "bar"],[3, 2, 1]} │
# └────────────────────────────────────┘

Index into struct fields with operators:

df.sql("SELECT nested -> 'c' -> 1 FROM self").item()
# 2

df.sql("SELECT nested -> 'c' ->> 1 FROM self").item()
# "2"

df.sql("SELECT nested -> '0' -> 0 FROM self").item()
# "baz"

df.sql("SELECT nested #> '{b,-1}' FROM self").item()
# "bar"

df.sql("SELECT nested #>> '{c,2}' FROM self").item()
# "1"

Footnotes

1. See: https://www.postgresql.org/docs/current/functions-json.html#FUNCTIONS-JSON-PROCESSING. ↩

[codecov]

Codecov Report

Attention: Patch coverage is 81.63265% with 9 lines in your changes missing coverage. Please review.

Project coverage is 80.89%. Comparing base (1252e4a) to head (abde40b).
Report is 1 commits behind head on main.

Files	Patch %	Lines
crates/polars-sql/src/keywords.rs	0.00%	7 Missing ⚠️
crates/polars-sql/src/sql_expr.rs	95.23%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #17226      +/-   ##
==========================================
- Coverage   80.89%   80.89%   -0.01%     
==========================================
  Files        1470     1470              
  Lines      192630   192679      +49     
  Branches     2750     2750              
==========================================
+ Hits       155835   155869      +34     
- Misses      36287    36302      +15     
  Partials      508      508              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[ritchie46]

Thanks! Can you rebase?

[alexander-beedie]

Thanks! Can you rebase?

On it ;)