EXPLAIN Statement

The EXPLAIN statement compiles a statement through Chalk SQL’s planner and optimizer and returns the resulting physical plan as text, without executing the query. EXPLAIN ANALYZE additionally executes the query and annotates the plan with runtime statistics.

​

Examples

-- Show the optimized physical plan without running the query
EXPLAIN SELECT u.user_id, sum(t.amount)
FROM "my_postgres.public.users" u
JOIN "my_bigquery.my_dataset.transactions" t ON u.user_id = t.user_id
GROUP BY u.user_id;

-- Run the query and include execution statistics in the plan
EXPLAIN ANALYZE SELECT count(*) FROM "my_bigquery.my_dataset.transactions";

​

Syntax

EXPLAIN statement;
EXPLAIN ANALYZE statement;

The result is a single row with a single string column named explain containing the plan.

​

Behavior

• EXPLAIN binds, optimizes, and compiles the statement without reading any data, so it surfaces planning-time errors such as missing tables or columns and unsupported constructs.
• EXPLAIN ANALYZE executes the statement to completion and returns the plan annotated with per-operator execution statistics. The query’s normal output rows are discarded; only the annotated plan is returned. Because the query really runs, EXPLAIN ANALYZE costs as much as the query itself.

EXPLAIN is useful for checking which parts of a query are pushed down into an underlying data source versus executed by Chalk’s engine, such as whether a WHERE filter was pushed into the data source scan.