query
Execute read-only SELECT statements against a DuckDB warehouse to fetch row results, with enforced limits and clear truncation notices.
Instructions
Run one read-only SELECT against the warehouse and return the rows.
Enforcement, in order: the statement is parsed and rejected unless it is a single SELECT; a LIMIT is injected if absent and lowered if it exceeds the server cap; execution is cancelled if it exceeds the time limit. When the result is truncated, the true total is counted and reported -- the output never implies it is complete when it is not.
Prefer aggregating in SQL over selecting raw rows. SELECT count(*), avg(x)
costs a handful of tokens; SELECT * costs hundreds and usually answers
less.
Args: sql (str): One SELECT statement in DuckDB SQL. max_rows (Optional[int]): Per-call row cap, clamped to the server cap (default 200). response_format (ResponseFormat): 'markdown' (default) or 'json'.
Returns: str: For 'markdown', an unpadded markdown table followed by a row-count footer that discloses truncation. For 'json', an object: { "columns": [str], "rows": [[Any]], "row_count": int, # rows returned "total_rows": int|null, # true total when truncated "truncated": bool, "elapsed_ms": float }
On failure: "Error: <message>" naming the recovery path.Examples: - Use when: "What was revenue by month in 2025?" -> aggregate in SQL. - Use when: "Show me 10 example rows from orders." - Don't use when: you do not yet know the column names (call describe_table first -- it is cheaper than a failed query).
Error Handling: - Non-SELECT statements, multiple statements, and filesystem functions are rejected before execution. - Queries exceeding the time limit are cancelled, not left running. - Unknown columns return DuckDB's message, which names the candidates.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | One SELECT statement in DuckDB SQL. CTEs, joins, window functions and UNION are supported. Anything that writes (INSERT, UPDATE, DELETE, CREATE, DROP, COPY, ATTACH, PRAGMA) is rejected, as are multiple statements separated by semicolons. | |
| max_rows | No | Row cap for this call. Defaults to the server cap (WAREHOUSE_MAX_ROWS, 200 by default) and can never exceed it. | |
| response_format | No | 'markdown' (default) is compact and cheap to read. 'json' returns columns and rows verbatim for programmatic use, at roughly 2-3x the token cost. | markdown |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |