SQL Explainer Prompt: Understand Any Query Step by Step

Use this prompt when you inherit a 200-line query, review a teammate’s SQL, or need to explain a report query to a non-engineer. Claude walks through it in execution order, describes what one output row means, and flags anything that could return wrong numbers.

The prompt

You are a database engineer who explains SQL clearly. The reader is {{AUDIENCE}}, so match your depth to them.

<query dialect="{{DIALECT}}">
{{SQL_QUERY}}
</query>

<schema>
{{SCHEMA_OR_NONE}}
</schema>

<plan>
{{EXPLAIN_OUTPUT_OR_NONE}}
</plan>

<instructions>
1. In one or two sentences, say what question this query answers.
2. Walk through the query in logical execution order (FROM and JOINs, WHERE, GROUP BY, HAVING, window functions, SELECT, ORDER BY, LIMIT), explaining each part in plain language.
3. Describe what one row of the result represents and list the output columns.
4. Flag correctness risks: join fan-out that inflates aggregates, NULL handling, implicit type casts, time zone issues, non-deterministic ordering.
5. Flag performance risks. If an EXPLAIN plan is provided, base this on the plan; otherwise mark these as likely, not certain.
6. Where the schema is missing, state your assumptions about keys and types explicitly.
7. Suggest improvements only where they fix a real risk, and show the rewritten SQL.
</instructions>

<output_format>
## What it answers
## Step-by-step
## Result shape
## Correctness risks
## Performance notes
## Assumptions
## Suggested rewrite (if any)
</output_format>

How to use it

• claude.ai: paste the query, plus schema and plan when you have them.
• Claude Code: point Claude at the .sql file or migration folder so it can read the schema itself. Save the prompt as a skill at .claude/skills/explain-sql/SKILL.md and pass the file path with $ARGUMENTS; see the skills guide. For live schema access, connect a database MCP server with a read-only user; see the MCP guide.
• API: useful for adding “explain this query” buttons to internal BI tools.

Variables

Variable	What to put there
{{AUDIENCE}}	“a junior analyst”, “a product manager”, “a senior DBA”
{{DIALECT}}	PostgreSQL, MySQL, BigQuery, Snowflake, SQLite
{{SQL_QUERY}}	The query
{{SCHEMA_OR_NONE}}	CREATE TABLE statements or “none”
{{EXPLAIN_OUTPUT_OR_NONE}}	Query plan output or “none”

Example output (illustrative)

## Correctness risks
- The LEFT JOIN to order_items before SUM(orders.total) repeats each order once per item,
  so revenue is overcounted. Aggregate order_items in a subquery first.

Tips and variations

• Reverse mode: describe the question in plain English and ask Claude to write the query, then run this prompt on its output as a self-check.
• Teaching mode: set the audience to “a beginner” and ask for a small example table showing intermediate results.