Explain a SQL query
Explains a complex SQL query clause by clause in logical execution order, shows intermediate results on a tiny example, and points out bugs and performance traps. Use when inheriting a query.
SQL is written in one order and evaluated in another: the SELECT list comes first on the page but is computed almost last. People who inherit a long query read it top to bottom and miss what actually shapes the result: a WHERE condition that silently turns a LEFT JOIN into an inner join, a join that multiplies rows before a SUM, NOT IN against a list that contains NULL. Watching a few rows flow through each step makes these visible in a way that prose does not.
Explain this queryOnly if [DIALECT] is given: ():
[QUERY]
Only if [SCHEMA] is given:
Schema:
- Say in one plain sentence what the query returns and what one row of the result represents (one customer, one customer per month, one order line).
- Walk through it in logical evaluation order: CTEs in dependency order, then
FROMand eachJOINwith its condition and join type,WHERE,GROUP BY, aggregates,HAVING, window functions,SELECTexpressions,DISTINCT,ORDER BY,LIMITorOFFSET. For each clause, say what it does to the set of rows in plain words (keeps, drops, multiplies, collapses, adds a column) and why the author probably wrote it. - Build a tiny example dataset of three to six rows per table that exercises the interesting cases: an unmatched row for each outer join, a
NULLwhere it matters, a duplicate key that causes fan-out, a group with one row and one with several. Show the intermediate result after each step that changes the rows, as small tables, ending with the final result. If the schema is not given, infer the columns from the query, label the inference, and keep the example consistent with it. - Point out bugs and traps, each tied to a line of the query and shown on the example data where possible:
- Correctness: outer joins undone by
WHEREconditions on the outer table,NOT INwithNULLs,COUNT(*)versusCOUNT(column)after outer joins, sums inflated by one-to-many joins,BETWEENon timestamps that drops the last day, integer division, ambiguous grouping in permissive dialects,DISTINCThiding a join problem, window frames that default toRANGE, time-zone conversions. - Performance: functions or casts on filtered columns that prevent index use, leading-wildcard
LIKE, correlated subqueries run per row,SELECT *in subqueries, sorting large sets forLIMITwith a bigOFFSET. Mark which are definite and which depend on data you have not seen.
- If the query can be written more clearly with the same result, show the simpler version and confirm it returns the same rows on the example data. Skip this if the query is already clear.
Pitch it at the level. For beginner, assume only basic SELECT, WHERE and JOIN, and define every other term (evaluation order, fan-out, window function) the first time you use it. For intermediate, define only window functions, recursive CTEs and dialect-specific features. For expert, skip definitions and spend the words on the traps and the evaluation order.
Scale the answer to the query. For a short query with no joins, aggregates, subqueries or window functions, show only the input table and the final result in the worked example and keep every section to a few lines.
- Follow the named dialect's rules. If no dialect is given, use standard SQL and note where common dialects behave differently for this query.
- Example data must be small and obviously fictional.
- Do not claim a performance problem without saying what it depends on (table size, indexes, the plan).
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
In one sentence
What it returns and what one row means.
Execution order
Numbered steps in evaluation order, each naming the clause and what it does to the rows.
Worked example
The input tables, then the intermediate tables after each step that changes the rows, then the final result.
Bugs and traps
Numbered. Each: the line, the problem, a demonstration on the example data, and the fix. "None found" if there are none.
Simpler version
A sql code block and one line on why it is equivalent, or "Not needed."
Questions
Anything about the data or intent that would change the explanation.
1 required value still a placeholder; the assistant will ask for it.
details
- kind
- Prompt: a task you run by name to get one finished thing back
- domain
- Software engineering
- category
- Learning to code
- level
- Beginner
- made for
- Data analyst, Software engineer, Backend engineer, Student
- risk
- read-only
- version
- v1.0.0 · experimental
- reviewed
- 2026-10-02
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md, ChatGPT, claude.ai
use in
npx @hermes-hq/hodios install explain-sql-query --target claude-codenpx skills add hermes-hq/hodios-dist --skill explain-sql-query -a claude-codeclaude plugin marketplace add hermes-hq/hodios-distclaude plugin install hodios-software-engineering@hodiosThe plugin brings every entry in this domain at once.
pairs well with
All of Learning to codeOptimise a slow SQL query
Speeds up a slow SQL query from its execution plan, proposing rewrites and indexes with expected gains and their write-cost trade-offs. Use when one query dominates latency or database load.
optimize-sql-queryReview analytical SQL
Reviews an analytical SQL query for logic errors that give wrong numbers, such as join fan-out, misplaced filters, NULLs, double counting and date or time-zone boundaries. Use before sharing results.
review-analysis-sqlExplain a concept with code
Explains a programming concept through the problem it solves, a minimal runnable example, a common mistake and a quick self-check, pitched at the learner's level. Use to learn or teach a concept.
explain-concept-with-codeAnswer a question with SQL
Turns a business question and a schema into an analytical SQL query, states the assumptions behind it and explains how to read the result. Use when you know the question but not the query.
answer-question-with-sqlSQL style rules
Standing rules for SQL an assistant writes, covering formatting, naming, explicit column lists, parameterised queries, NULL handling, data types and safe migrations.
sql-style-rulesExplain a codebase
Explains an unfamiliar codebase. Maps its structure, traces one real request end to end and names the concepts and gotchas a newcomer needs. Use when joining a project or reading an unknown repo.
explain-codebase