Aller au contenu principal

Run Query

POST 
/v1/query

Run an inline alias-only SQL query across the caller's own datasets.

  • datasetIds (plural, OPTIONAL):
    • Provided: each id resolves to that dataset's alias; the SQL joins the aliases. Deny-don't-drop — if the key is not authorized for EVERY id, the whole query is rejected (403 query_dataset_forbidden), never executed against the granted subset.
    • Omitted: the server INFERS the set from the aliases the SQL references (each resolved to a dataset by clean_sql_name for the calling account), then applies the SAME authorization. An alias that matches no dataset in the account → 400 query_dataset_unresolved. An inferred dataset the key isn't granted is still rejected (403) — inference is a DX convenience, NOT an authorization relaxation.
  • Dataset readiness: only a READY dataset has an Iceberg table behind it. A participating dataset still ingesting (PENDING/DOWNLOADING/ PROCESSING) → 400 query_dataset_not_ready; one whose ingestion failed (FAILED) → 400 query_dataset_failed. Both name the dataset and its processingStatus, in both backend and wasm modes.
  • sql: inline, alias-only. Physical tables / DDL / file+remote readers are rejected by the embed SQL validator (403 embed_sql_invalid).
  • params: optional pass-through column filters, bound as escaped literals (never string-interpolated). A filter on a phantom column fails closed (403 embed_filter_invalid).
  • type (Phase 208): backend (default) or wasm.
    • wasm asks for a PLAN instead of rows: the rewritten SQL plus one presigned Parquet extract per participating dataset, which the caller runs locally in DuckDB-WASM. Authorization, alias-only validation and filter injection ALL still happen server-side, in that order, BEFORE the capability check — asking for wasm cannot skip a single gate.
    • If any participating dataset is not wasm-capable (no Iceberg snapshot, or an extract over WASM_EXTRACT_MAX_BYTES), the query executes server-side exactly as today and the response reports mode: "backend" with a fallbackReason. Never a silent downgrade.

Returns typed columnar { columns:[{name,type}], rows } — or, in wasm mode, { mode:"wasm", plan:{ sql, sources } }. mode always states what the query ACTUALLY ran as. Metered through the existing usage/credits mechanism in both lanes. Result transport (inline vs presigned object-storage blob) is an internal decision hidden by the SDK's query().

Request​

Responses​

Successful Response