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. Useparams to inject values, and destination/saveMode to persist the result as a lake table.
Distributed runs
Passdistributed: 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.