lake-query

Lake Query

oleander routes the query. It parses the SQL, estimates how much data the referenced tables hold, and picks the engine and machine size to match. Pick the tool by whether the query changes data — not by how big it is.

Tool	Use for
query_run	Reads. Rows come back on the call.
query_submit	Anything that changes data, and reads too large to return interactively.
spark_sql_submit	Spark jobs needing a durable job name or explicit machine types.

Leave engine as auto unless the user asked for a specific one. Every response carries engine_decision; use its reasons when telling the user why a query ran the way it did.

Reads — query_run

{ "sql": "SELECT district, count(*) FROM oleander.default.sf_311 GROUP BY 1" }

query_run is read-only and enforces it: INSERT, UPDATE, DELETE, MERGE, CREATE, ALTER, DROP, and TRUNCATE are rejected before the request goes out. That is what makes its readOnlyHint true, so clients can skip the confirmation prompt. CTAS and RTAS are not supported — pass the SELECT to query_submit with a destination instead.

If that rejection fires on a genuine read, a mutating keyword is appearing somewhere in the text (often inside a string literal). Rewrite it to avoid the bare keyword.

A read too large to return interactively is not run. It comes back as a routing or upgrade error naming query_submit.

Writes — query_submit

Two shapes go through this tool:

• A SELECT plus a destination — the result is written to that table.
• A statement that names its own target (INSERT/UPDATE/DELETE/MERGE/DDL) with no destination.

{
  "sql": "SELECT * FROM oleander.default.sf_311 WHERE opened >= TIMESTAMP '2026-01-01 00:00:00'",
  "destination": "my_namespace.sf_311_2026",
  "write_mode": "overwrite",
  "confirm": true
}

confirm: true is required — it is a literal in the schema, not a boolean, so omitting it fails validation. A SELECT with no destination also fails validation: reads belong in query_run.