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

```ts theme={null}
const result = await client.polars({
  query: "SELECT day, count(*) AS n FROM events GROUP BY day",
  tables: [{ alias: "events", table: "default.events" }],
});

console.log(result.results?.columns, result.results?.rows);
console.log(result.row_count, result.execution_time);
```

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

```ts theme={null}
const scripted = await client.polars({
  script: myPolarsScript, // Python source using polars
  params: { start_date: "2026-07-01" },
  destination: "default.polars_out",
  saveMode: "overwrite",
});

if (scripted.saved) {
  console.log("Wrote", scripted.saved.rows_written, "rows to", scripted.saved.table);
}
```

### Distributed runs

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

```ts theme={null}
const distributed = await client.polars({
  query: "SELECT day, count(*) AS n FROM events GROUP BY day",
  tables: ["default.events"],
  distributed: true,
  destination: "default.daily_counts",
  clusterSize: 4,
});
```

### Parameters

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

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

<ParamField body="options.tables" type="(string | { alias, table })[]" default="[]">
  Table bindings. Required (at least one) in query mode.
</ParamField>

<ParamField body="options.params" type="Record<string, unknown>" default="{}">
  Parameters made available to the script.
</ParamField>

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

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

<ParamField body="options.instanceType" type="string">
  Instance type for distributed runs.
</ParamField>

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

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

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

<ParamField body="options.saveMode" type="string" 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.
</Note>

### Return type: `PolarsResult`

| Field            | Type            | Description                                                     |
| ---------------- | --------------- | --------------------------------------------------------------- |
| `success`        | `boolean`       | Whether the run executed successfully                           |
| `results`        | `object`        | Results with `columns`, `column_types`, and `rows`              |
| `row_count`      | `number`        | Number of rows returned                                         |
| `execution_time` | `string`        | Run execution time                                              |
| `saved`          | nullable object | `table`, `rows_written`, and `mode` when results were persisted |
| `compute`        | `object`        | `mode`, `distributed`, `instanceType`, `clusterSize`            |