query_datasets

The main verb for analysing datasets without pulling all their rows into the agent’s context. Write DuckDB-dialect SQL that references aliases you declare in the datasets parameter; the server resolves those to CSV files in S3 and runs the query via DuckDB’s httpfs extension (authenticated range reads — no full downloads).

When to use it

• Filter, sort, slice, or paginate a dataset returned by another tool.
• Aggregate or pivot across one or more datasets.
• Join two datasets — e.g. prospects joined to their accounts.

For raw downloads, use download_dataset.

Inputs

Parameter	Type	Required	Description
datasets	object	Yes	Map of alias → dataset_id used by the SQL. Each alias must be a plain identifier ([A-Za-z_][A-Za-z0-9_]*).
sql	string	Yes	DuckDB-dialect SELECT (optionally wrapped in CTEs).
row_limit	integer	No	Max rows returned inline. Default 100, max 500.
persist_as_dataset	boolean	No	If true, the full result is also written to a new CSV dataset; the response includes its dataset_id in persisted_dataset.
target_tenant_id	string	No	Super tenants only.

Dialect

DuckDB. You can use DuckDB-specific constructs: USING SAMPLE n ROWS, QUALIFY, PIVOT, UNPIVOT, LIST_AGG, REGEXP_MATCHES, GROUPING SETS, window functions, recursive CTEs.

Returns

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

Guidance for the agent

• Prefer aggregations over SELECT *. If you need raw rows, set row_limit explicitly and use ORDER BY + LIMIT.
• Join multiple datasets by giving each an alias and using FROM a JOIN b ON ....
• If the result itself is too large to show, set persist_as_dataset=True and query the new dataset in a follow-up.
• Only SELECT is allowed. Functions that read files directly (read_csv, read_csv_auto, read_parquet, attach, copy, http_*) are rejected — always reference datasets by alias.

Examples

Group by country:

SELECT contact_country, COUNT(*) AS n
FROM p
GROUP BY 1
ORDER BY n DESC

{ "datasets": { "p": "ds_abc" }, "sql": "SELECT contact_country, COUNT(*) AS n FROM p GROUP BY 1 ORDER BY n DESC" }

Top-10 biggest companies:

SELECT name, size FROM c ORDER BY size DESC LIMIT 10

{ "datasets": { "c": "ds_xyz" }, "sql": "SELECT name, size FROM c ORDER BY size DESC LIMIT 10", "row_limit": 10 }

Persist a filtered slice as a new dataset:

SELECT * FROM p WHERE seniority_executive IS NOT NULL

{ "datasets": { "p": "ds_abc" }, "sql": "SELECT * FROM p WHERE seniority_executive IS NOT NULL", "persist_as_dataset": true }