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

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

FieldTypeDescription
successbooleanWhether the run executed successfully
resultsobjectResults with columns, column_types, and rows
row_countnumberNumber of rows returned
execution_timestringRun execution time
savednullable objecttable, rows_written, and mode when results were persisted
computeobjectmode, distributed, instanceType, clusterSize