explain
View a query's physical plan and estimated row count without executing it. Use when a query is expensive or timed out to spot costly joins before they waste compute.
Instructions
Show the query plan and estimated row count WITHOUT executing the query.
Use this when a query might be expensive, or after one has timed out. The estimate comes from DuckDB's optimizer, so it is an estimate, not a guarantee -- but it is enough to catch an accidental cross join before it runs for fifteen seconds.
Args: sql (str): The SELECT to plan. It is not executed.
Returns: str: Markdown containing the estimated cardinality, a verdict on whether the query is worth running, and the physical plan.
On failure: "Error: <guard message>" for non-SELECT input.Examples: - Use when: a previous query hit the timeout. - Use when: joining two large tables for the first time. - Don't use when: you just want the answer (call query directly).
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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |