Polars - oleander

`polars(options)`

Run a Polars SQL query or a Python script over lake tables. Provide exactly one of query or script. If the API rejects the run, the SDK raises instead of returning a failed result.

Query mode

Query mode requires at least one table binding, either as "namespace.table" (the alias defaults to the table name) or as PolarsTable(alias=..., table=...).

from oleander_sdk import PolarsOptions, PolarsTable

result = await client.polars(PolarsOptions(
    query="SELECT day, count(*) AS n FROM events GROUP BY day",
    tables=[PolarsTable(alias="events", table="default.events")],
))

print(result.results.columns, result.results.rows)
print(result.row_count, result.execution_time)

Script mode

Pass a Python script that uses Polars. Use params to inject values, and destination/save_mode to persist the result as a lake table.

scripted = await client.polars(PolarsOptions(
    script=my_polars_script,  # Python source using polars
    params={"start_date": "2026-07-01"},
    destination="default.polars_out",
    save_mode="overwrite",
))

if scripted.saved:
    print(f"Wrote {scripted.saved.rows_written} rows to {scripted.saved.table}")

Distributed runs

Pass distributed=True with a destination to run on Polars Cloud.

distributed = await client.polars(PolarsOptions(
    query="SELECT day, count(*) AS n FROM events GROUP BY day",
    tables=["default.events"],
    distributed=True,
    destination="default.daily_counts",
    cluster_size=4,
))

Parameters

str

Polars SQL query. Provide exactly one of query or script.

str

Python script source using Polars. Provide exactly one of query or script.

list[str | PolarsTable]

default:"[]"

Table bindings. Required (at least one) in query mode.

dict[str, Any]

default:"{}"

Parameters made available to the script.

bool

default:"False"

Run on Polars Cloud. Requires destination.

str

Catalog to resolve tables against.

str

Instance type for distributed runs.

int

Cluster size for distributed runs, from 1 to 64.

int

vCPUs per instance, from 1 to 32.

str

Lake table to write results to. Required when distributed=True.

str

default:"overwrite"

overwrite or append. Applies when writing to destination.

Polars runs execute compute synchronously and can take minutes when a sandbox cold-starts or a distributed cluster spins up. The SDK uses an extended request timeout of 30 minutes for Polars runs.

Return type: `PolarsResult`

Field	Type	Description
`success`	`bool`	Whether the run executed successfully
`results`	`Optional[QueryResultColumns]`	Results with `columns`, `column_types`, and `rows`
`row_count`	`Optional[int]`	Number of rows returned
`execution_time`	`Optional[str]`	Run execution time
`saved`	`Optional[PolarsSaved]`	`table`, `rows_written`, and `mode` when results were persisted
`compute`	`Optional[PolarsCompute]`	`mode`, `distributed`, `instance_type`, `cluster_size`

​polars(options)

​Query mode

​Script mode

​Distributed runs

​Parameters

​Return type: PolarsResult

`polars(options)`

Query mode

Script mode

Distributed runs

Parameters

Return type: `PolarsResult`