query_datasets

query_datasets is the main verb for analysing a saved result without pulling every row into context. Declare aliases, reference them in SQL, and the server resolves each alias to its CSV in S3 and runs the query through DuckDB’s httpfs (range reads — no full downloads).

Inputs

Parameter	Type	Required	Description
datasets	object	Yes	Map of alias -> dataset_id. Each alias must be a plain identifier.
sql	string	Yes	DuckDB-dialect SELECT (CTEs allowed).
row_limit	integer	No	Max rows returned inline. Default 100, max 500.
persist_as_dataset	boolean	No	Also write the full result to a new dataset; the id comes back in persisted_dataset.
target_tenant_id	string	No	Super tenants only.

Dialect

Full DuckDB: USING SAMPLE n ROWS, QUALIFY, PIVOT, UNPIVOT, LIST_AGG, REGEXP_MATCHES, GROUPING SETS, window functions, and recursive CTEs all work.

Only SELECT statements are allowed. File-reading functions (read_csv, read_csv_auto, read_parquet, attach, copy, http_*) are rejected — always reference datasets by alias.

Example

{
  "datasets": { "people": "ds_abc123", "accounts": "ds_def456" },
  "sql": "SELECT a.industry, COUNT(DISTINCT p.linkedin_url) AS people FROM people p JOIN accounts a ON p.current_company_url = a.linkedin_url GROUP BY 1 ORDER BY people DESC",
  "row_limit": 50
}

Returns

JSON with columns, rows (up to row_limit), row_count, truncated, and optionally persisted_dataset.

Notes & limits

• Prefer aggregations over SELECT *.
• If a result is too large to show, set persist_as_dataset=true and keep working against the new handle — or hand it to download_dataset if the user wants the file.
• This queries your saved results, not the data lake. Data-lake questions go through ask_onfire.