Query

The SDK has two query methods and one legacy one. queryRun reads, querySubmit writes, and both go through the query router, which picks the engine and machine size for you.

`queryRun(sqlOrOptions)`

Runs a query and returns the rows on the call. oleander parses the SQL, estimates how much data the referenced tables hold, and picks the engine (duckdb, polars, bloom) and machine size to match, so leave engine as auto unless you want a specific one. The choice and the reasoning behind it come back in engine_decision.

const result = await oleander.queryRun(
  "SELECT * FROM oleander.default.flowers LIMIT 10",
);

console.log(result.results?.columns, result.results?.rows);
console.log(result.row_count, result.execution_time);
console.log(result.engine_decision?.engine, result.engine_decision?.reasons);

queryRun is read-only. SQL that could change data is rejected before the request goes out - use querySubmit for those.

Explain without running

Pass explain: true to see which engine a query would take, its estimated input size, and whether your plan allows it, without running anything or spending compute.

const { engine_decision } = await oleander.queryRun({
  sql: "SELECT * FROM oleander.default.events",
  explain: true,
});

console.log(engine_decision?.engine, engine_decision?.size_band);

Do this before a query you expect to be large.

Polars scripts

Pass script instead of sql to run a Polars DataFrame script that assigns result, listing the tables it reads in tables. This forces the Polars engine.

const scripted = await oleander.queryRun({
  script: "result = events.group_by('day').len()",
  tables: [{ alias: "events", table: "default.events" }],
});

Parameters

string

The SQL query to run. Pass a bare string as the only argument for the common case, or use the options object for anything else. Mutually exclusive with script.

string

A Polars DataFrame script that assigns result. Requires tables.

QueryTable[]

Tables the script reads, as { alias, table }.

"auto" | "duckdb" | "polars" | "bloom"

default:"\"auto\""

Ask for a specific engine. An impossible combination returns an engine capability error rather than rerouting.

boolean

default:"false"

Return the routing decision without executing.

`querySubmit(options)`

Covers everything that changes data: a SELECT plus a destination to write it to, and a statement that names its own target (INSERT, UPDATE, DELETE, MERGE, DDL) with no destination. It also takes reads too large to return interactively. Whether the write finishes on the call depends on the engine the router picked, so read state. Result rows are never returned, only row_count when it is known.

const submitted = await oleander.querySubmit({
  sql: "SELECT day, count(*) AS n FROM oleander.default.events GROUP BY day",
  destination: "default.daily_counts",
  writeMode: "overwrite", // or "append"
});

console.log(submitted.state, submitted.output_table, submitted.run_id);

`state`	Meaning
`COMPLETE`	The write already landed. Nothing to poll.
`SUBMITTED`	A job is running. `run_id` is returned and the write is not visible yet.

`querySubmitAndWait(options)`

Submits and polls until an asynchronous run finishes. A write that lands inline returns immediately with no run.

const { state, run } = await oleander.querySubmitAndWait({
  sql: "INSERT INTO oleander.default.daily_counts SELECT * FROM staging.daily",
});

console.log(state); // COMPLETE | FAIL | ABORT

Parameters

string

The statement to run. With a destination, a SELECT; without one, a statement that names its own target.

string

Table to write the result to, as namespace.table.

"overwrite" | "append"

default:"\"overwrite\""

Applies to a destination write. A statement that names its own target carries its own semantics.

"auto" | "duckdb" | "polars" | "bloom" | "spark"

default:"\"auto\""

Ask for a specific engine.

boolean

default:"false"

Return the routing decision without submitting anything.

`query(sql, options?)`

query predates the router. It always runs DuckDB, sized by the org’s default sandbox setting rather than by the query. Prefer queryRun; reach for this only when you need save: true.

Executes SQL against the lake on DuckDB, with optional auto-save by query hash. If the API rejects the query, the SDK throws instead of returning a failed result.

const result = await oleander.query(
  "SELECT * FROM oleander.default.flowers LIMIT 10",
  { save: true },
);

if (result.saved_table_name) console.log("Saved to:", result.saved_table_name);

Parameters

string

required

The SQL query to execute. Supports DuckDB SQL syntax.

boolean

default:"false"

When true, persists query results as a table. The table name is returned in saved_table_name.

Return fields

Field	Type	Description
`success`	`boolean`	Whether the query executed successfully
`results`	`object`	`columns`, `column_types`, and `rows`. Reads only.
`row_count`	`number`	Number of rows returned or written
`execution_time`	`string`	Execution time, for example `"42ms"`
`engine_decision`	`object`	`engine`, `reasons`, `size_band`, `sandbox`. `queryRun` and `querySubmit` only.
`compute`	`object`	The sandbox that actually served the run - the machine the org is billed for
`state`	`string`	`COMPLETE` or `SUBMITTED`. `querySubmit` only.
`run_id`	`string`	Run to poll when `state` is `SUBMITTED`
`output_table`	`string`	Destination table for a write
`saved_table_name`	`string`	Table name if `save: true` was used on `query`

Iterating over results

const result = await oleander.queryRun(
  "SELECT species, sepal_length FROM oleander.default.flowers LIMIT 10",
);

const { columns, rows } = result.results!;
const speciesIdx = columns.indexOf("species");
const sepalLengthIdx = columns.indexOf("sepal_length");

for (const row of rows) {
  const species = row[speciesIdx] as string;
  const sepalLength = row[sepalLengthIdx] as number;
  // process each record ...
}

TypeScript

Python

`queryRun(sqlOrOptions)`

Explain without running

Polars scripts

Parameters

`querySubmit(options)`

`querySubmitAndWait(options)`

Parameters

`query(sql, options?)`

Parameters

Return fields

Iterating over results

​queryRun(sqlOrOptions)

​Explain without running

​Polars scripts

​Parameters

​querySubmit(options)

​querySubmitAndWait(options)

​Parameters

​query(sql, options?)

​Parameters

​Return fields

​Iterating over results

`queryRun(sqlOrOptions)`

Explain without running

Polars scripts

Parameters

`querySubmit(options)`

`querySubmitAndWait(options)`

Parameters

`query(sql, options?)`

Parameters

Return fields

Iterating over results