---
name: sql-query-explainer
description: "Walks through a SQL query step by step in plain language, then points out where the logic could give wrong numbers or the plan could be slow. Use when a SQL query is unfamiliar, inherited or suspect and needs a step-by-step explanation with correctness and performance risks pointed out. Do not use for writing a new query from a question or tuning a database server. Related topics: data, education."
---

# SQL Query Explainer

Walks through a SQL query step by step in plain language, then points out where the logic could give wrong numbers or the plan could be slow.

## When to use

Use this skill when a SQL query is unfamiliar, inherited or suspect and needs a step-by-step explanation with correctness and performance risks pointed out. Do not use it for writing a new query from a question or tuning a database server.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Summarise in one sentence what the query returns and how the result is used.
3. Walk through the clauses in logical execution order and say which rows each one keeps or removes.
4. Describe every join with its key and flag any that could multiply rows.
5. Check for correctness traps such as fan-out, NULL handling, accidental inner joins and date boundaries.
6. List speed risks and suggest rewrites with check queries that would confirm the totals.

## Inputs

- **Query** (longer free text)
- **Database** (choose one: PostgreSQL, MySQL, SQL Server, BigQuery, SQLite, Snowflake)
- **Table descriptions** (longer free text)
- **Reader's SQL level** (choose one: Beginner, Comfortable, Advanced)
- **What the result is used for** (free text, e.g. "A weekly revenue report")
- **Known problem** (longer free text)

## Output

A one-sentence summary, a clause-by-clause walkthrough pitched at the reader's level, a list of correctness and speed risks, and suggested rewrites with check queries.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### SQL Query Explainer

Explain this SQL query.

- Query: {{Query}}
- Database: {{Database}}
- Table descriptions: {{Table descriptions}}
- Reader's SQL level: {{Reader's SQL level}}
- What the result is used for: {{What the result is used for}}
- Known problem: {{Known problem}}

Start with one sentence on what the query returns and for whom. Then walk through it in logical execution order rather than written order: FROM and joins, WHERE, GROUP BY, HAVING, window functions, SELECT, ORDER BY and LIMIT, explaining each clause and the rows it keeps or removes. Describe each join with its type, its key and whether it could multiply rows when the key is not unique. Pitch the language to the reader's level and define terms for beginners. Then look for correctness traps: join fan-out inflating sums, NULL handling in comparisons and counts, a filter on the outer table that silently turns a left join into an inner join, time zone and date boundaries, and integer division. Look for speed traps: functions on indexed columns, leading wildcards, correlated subqueries, missing limits, and large sorts. Finish with a short list of suggested rewrites and the check queries that would confirm the totals.

## Pitfalls

- Explaining the clauses in written order, which hides that WHERE runs before SELECT aliases exist.
- Missing a fan-out from a one-to-many join, which makes totals look plausible but wrong.
- Calling a query slow without table sizes or a plan, when the real cost depends on the data.