Skip to main content

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 throws 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 { alias, table }.

Script mode

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

Distributed runs

Pass distributed: true with a destination to run on Polars Cloud.

Parameters

string
Polars SQL query. Provide exactly one of query or script.
string
Python script source using Polars. Provide exactly one of query or script.
(string | { alias, table })[]
default:"[]"
Table bindings. Required (at least one) in query mode.
Record<string, unknown>
default:"{}"
Parameters made available to the script.
boolean
default:"false"
Run on Polars Cloud. Requires destination.
string
Catalog to resolve tables against.
string
Instance type for distributed runs.
number
Cluster size for distributed runs, from 1 to 64.
number
vCPUs per instance, from 1 to 32.
string
Lake table to write results to. Required when distributed is true.
string
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.

Return type: PolarsResult