> ## 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. # Run a Polars workload > Execute a Polars workload against your Iceberg lake tables. Supports two modes: **query** (Polars SQL run against registered tables) and **script** (user-authored Python that assigns `result` to a LazyFrame or DataFrame). Workloads run in an isolated sandbox; pass `distributed: true` to offload execution to Polars Cloud. **Beta:** Observability (lineage, traces, logs) is not yet captured for Polars workloads. **Cost note:** Distributed execution incurs Polars Cloud compute charges in addition to oleander usage. Start small and scale up as needed. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/warehouse/polars openapi: 3.0.1 info: title: Oleander API description: >- Oleander implements the api spec as defined by OpenLineage to ingest data. We also provide a RESTful API to extract data within our system. version: 1.0.0 servers: - url: https://oleander.dev security: - bearerAuth: [] paths: /api/v1/warehouse/polars: post: summary: Run a Polars workload description: >- Execute a Polars workload against your Iceberg lake tables. Supports two modes: **query** (Polars SQL run against registered tables) and **script** (user-authored Python that assigns `result` to a LazyFrame or DataFrame). Workloads run in an isolated sandbox; pass `distributed: true` to offload execution to Polars Cloud. **Beta:** Observability (lineage, traces, logs) is not yet captured for Polars workloads. **Cost note:** Distributed execution incurs Polars Cloud compute charges in addition to oleander usage. Start small and scale up as needed. operationId: runPolars requestBody: required: true content: application/json: schema: type: object required: - mode properties: mode: type: string enum: - query - script description: >- 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`. query: type: string description: 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: type: array description: >- Tables to register for query mode. Each entry is either `alias=namespace.table` or an object `{alias, table}`. Required when `mode` is `query`. items: oneOf: - type: string example: flowers=default.flowers - type: object required: - alias - table properties: alias: type: string table: type: string script: type: string description: >- 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') limit = int(params.get('limit', 50)) flowers = scan(table) result = ( flowers.group_by('species') .agg( pl.len().alias('count'), pl.col('sepal_length').mean().round(2).alias('avg_sepal_length'), pl.col('petal_length').mean().round(2).alias('avg_petal_length'), ) .sort('avg_sepal_length', descending=True) .head(limit) ) params: type: object description: >- Key-value parameters available inside a script as the `params` dict. additionalProperties: type: string example: table: default.flowers limit: '25' distributed: type: boolean description: Run the workload on Polars Cloud instead of a local sandbox. default: false instanceType: type: string description: >- Polars Cloud instance type. Only used when `distributed` is `true`. example: t4g.medium clusterSize: type: integer description: >- Number of Polars Cloud nodes. Only used when `distributed` is `true`. example: 4 vcpus: type: integer description: >- Sandbox vCPU tier for local (non-distributed) execution. Valid values: 2, 4, 8, 16, 32. enum: - 2 - 4 - 8 - 16 - 32 default: 2 catalog: type: string description: Catalog name to query against. default: oleander destination: type: string description: >- Write results to a lake table. Format: `namespace.table`. If omitted, results are returned inline. example: default.flower_summary saveMode: type: string enum: - overwrite - append description: >- How to write to `destination`. `overwrite` replaces the table; `append` adds rows. default: overwrite responses: '200': description: Workload executed successfully content: application/json: schema: $ref: '#/components/schemas/PolarsResponse' '400': description: Invalid request or script/query error. content: application/json: schema: type: object properties: error: type: string details: type: string '401': description: Unauthorized – missing or invalid Bearer token. content: application/json: schema: type: object properties: error: type: string example: Unauthorized '500': description: Unexpected error. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: PolarsResponse: type: object properties: success: type: boolean description: Whether the workload executed successfully. results: type: object description: >- Inline results (omitted when `destination` is set and `distributed` is true). properties: columns: type: array items: type: string description: Column names in result order. column_types: type: array items: type: string description: Polars dtype string for each column (e.g. `Int64`, `Utf8`). rows: type: array items: type: array items: {} description: Result rows as arrays of values. row_count: type: integer description: Total number of rows in the result. execution_time: type: string description: Wall-clock time for the workload (e.g. `"340ms"`). error: type: string description: Error message if `success` is `false`. saved: type: object description: Present when `destination` was set. properties: table: type: string description: Full `namespace.table` identifier of the written table. rows_written: type: integer description: Number of rows written. mode: type: string description: '`overwrite` or `append`.' compute: type: object description: Compute environment details. properties: mode: type: string description: >- `"daytona"` for local sandbox execution, `"polars-cloud"` for distributed. distributed: type: boolean instanceType: type: string nullable: true clusterSize: type: integer nullable: true Error: required: - status type: object properties: status: type: integer format: int32 default: 500 securitySchemes: bearerAuth: type: http scheme: bearer ````