Skip to main content
POST
/
api
/
v1
/
warehouse
/
polars
Run a Polars workload
curl --request POST \
  --url https://oleander.dev/api/v1/warehouse/polars \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "query": "SELECT species, avg(sepal_length) AS avg_sepal_length, avg(petal_length) AS avg_petal_length FROM flowers GROUP BY species ORDER BY avg_sepal_length DESC",
  "tables": [
    "flowers=default.flowers"
  ],
  "script": "table = params.get('table', 'default.flowers')\nlimit = int(params.get('limit', 50))\n\nflowers = scan(table)\n\nresult = (\n    flowers.group_by('species')\n    .agg(\n        pl.len().alias('count'),\n        pl.col('sepal_length').mean().round(2).alias('avg_sepal_length'),\n        pl.col('petal_length').mean().round(2).alias('avg_petal_length'),\n    )\n    .sort('avg_sepal_length', descending=True)\n    .head(limit)\n)",
  "params": {
    "table": "default.flowers",
    "limit": "25"
  },
  "distributed": false,
  "instanceType": "t4g.medium",
  "clusterSize": 4,
  "vcpus": 2,
  "catalog": "oleander",
  "destination": "default.flower_summary",
  "saveMode": "overwrite"
}
EOF
{
  "success": true,
  "results": {
    "columns": [
      "<string>"
    ],
    "column_types": [
      "<string>"
    ],
    "rows": [
      [
        "<unknown>"
      ]
    ]
  },
  "row_count": 123,
  "execution_time": "<string>",
  "error": "<string>",
  "saved": {
    "table": "<string>",
    "rows_written": 123,
    "mode": "<string>"
  },
  "compute": {
    "mode": "<string>",
    "distributed": true,
    "instanceType": "<string>",
    "clusterSize": 123
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
mode
enum<string>
required

Execution mode. query runs a Polars SQL expression against registered tables. script executes a Python script that has pl, scan(table), and params in scope and must assign result.

Available options:
query,
script
​
query
string

Polars SQL query string. Required when mode is query.

Example:

"SELECT species, avg(sepal_length) AS avg_sepal_length, avg(petal_length) AS avg_petal_length FROM flowers GROUP BY species ORDER BY avg_sepal_length DESC"

​
tables
(string | object)[]

Tables to register for query mode. Each entry is either alias=namespace.table or an object {alias, table}. Required when mode is query.

Example:

"flowers=default.flowers"

​
script
string

Python script source for script mode. The script runs with pl (polars), scan(table), params, and catalog in scope. It must assign result to a Polars LazyFrame or DataFrame. Do not call .collect() or .remote() inside the script — oleander handles execution.

Example:

"table = params.get('table', 'default.flowers')\nlimit = int(params.get('limit', 50))\n\nflowers = scan(table)\n\nresult = (\n flowers.group_by('species')\n .agg(\n pl.len().alias('count'),\n pl.col('sepal_length').mean().round(2).alias('avg_sepal_length'),\n pl.col('petal_length').mean().round(2).alias('avg_petal_length'),\n )\n .sort('avg_sepal_length', descending=True)\n .head(limit)\n)"

​
params
object

Key-value parameters available inside a script as the params dict.

Example:
{ "table": "default.flowers", "limit": "25" }
​
distributed
boolean
default:false

Run the workload on Polars Cloud instead of a local sandbox.

​
instanceType
string

Polars Cloud instance type. Only used when distributed is true.

Example:

"t4g.medium"

​
clusterSize
integer

Number of Polars Cloud nodes. Only used when distributed is true.

Example:

4

​
vcpus
enum<integer>
default:2

Sandbox vCPU tier for local (non-distributed) execution. Valid values: 2, 4, 8, 16, 32.

Available options:
2,
4,
8,
16,
32
​
catalog
string
default:oleander

Catalog name to query against.

​
destination
string

Write results to a lake table. Format: namespace.table. If omitted, results are returned inline.

Example:

"default.flower_summary"

​
saveMode
enum<string>
default:overwrite

How to write to destination. overwrite replaces the table; append adds rows.

Available options:
overwrite,
append

Response

Workload executed successfully

​
success
boolean

Whether the workload executed successfully.

​
results
object

Inline results (omitted when destination is set and distributed is true).

​
row_count
integer

Total number of rows in the result.

​
execution_time
string

Wall-clock time for the workload (e.g. "340ms").

​
error
string

Error message if success is false.

​
saved
object

Present when destination was set.

​
compute
object

Compute environment details.