> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleander.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Polars

> Run Polars SQL queries or Python scripts over lake tables.

## `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=...)`.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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

<ParamField body="options.query" type="str">
  Polars SQL query. Provide exactly one of `query` or `script`.
</ParamField>

<ParamField body="options.script" type="str">
  Python script source using Polars. Provide exactly one of `query` or `script`.
</ParamField>

<ParamField body="options.tables" type="list[str | PolarsTable]" default="[]">
  Table bindings. Required (at least one) in query mode.
</ParamField>

<ParamField body="options.params" type="dict[str, Any]" default="{}">
  Parameters made available to the script.
</ParamField>

<ParamField body="options.distributed" type="bool" default="False">
  Run on Polars Cloud. Requires `destination`.
</ParamField>

<ParamField body="options.catalog" type="str">
  Catalog to resolve tables against.
</ParamField>

<ParamField body="options.instance_type" type="str">
  Instance type for distributed runs.
</ParamField>

<ParamField body="options.cluster_size" type="int">
  Cluster size for distributed runs, from 1 to 64.
</ParamField>

<ParamField body="options.vcpus" type="int">
  vCPUs per instance, from 1 to 32.
</ParamField>

<ParamField body="options.destination" type="str">
  Lake table to write results to. Required when `distributed=True`.
</ParamField>

<ParamField body="options.save_mode" type="str" default="overwrite">
  `overwrite` or `append`. Applies when writing to `destination`.
</ParamField>

<Note>
  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.
</Note>

### 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`          |