Query workspace

The Query workspace is a human interface over the same broker used by POST /v1/sql, SDKs, and MCP. It never bypasses the signed-in principal's Source and dataset grants.

Catalogue

The left catalogue tree lists granted Sources, datasets, fields, DuckDB types, classifications, and freshness. Use the displayed three-part relation exactly:

"source_alias"."logical_schema"."logical_table"

Logical names are stable product identifiers; provider names, S3 locations, and internal DuckLake metadata are not valid query targets.

Editor and execution

Write one SELECT, or a CTE chain ending in SELECT. The editor supports SQL syntax assistance but the server remains authoritative. A run receives one idempotency key and is admitted only after SQL, grants, relation resolution, scan estimate, rate, concurrency, and budget checks pass.

Use Stop to propagate cancellation through the broker to the isolated worker. Cancellation is durable: a canceled, timed-out, or revoked execution cannot later return a result.

Results

The result grid shows returned columns, types, rows, row count, truncation, duration, estimated input bytes, and receipt identifier. truncated: true means the row or serialized-byte bound was reached; add deterministic ordering and a keyset predicate for the next page. Do not infer completeness from a truncated result.

Receipts

Each request creates a content-free receipt with the canonical SQL hash, Sources and datasets, starting and ending grant versions, state, rows, truncation, estimated bytes, duration, timestamps, and error code. Query result content is never stored in the receipt.

Typical receipt states are queued, running, succeeded, denied, failed, timed_out, revoked, and canceled. Use the correlation ID from an error together with the receipt ID when investigating Activity.

See SQL catalogue and limits for accepted syntax, parameter binding, provenance columns, and hard bounds.