hermes

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.

context

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.

task

Explain this queryOnly if [DIALECT] is given: ():

[QUERY]

Only if [SCHEMA] is given:

Schema:

  1. 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).
  2. Walk through it in logical evaluation order: CTEs in dependency order, then FROM and each JOIN with its condition and join type, WHERE, GROUP BY, aggregates, HAVING, window functions, SELECT expressions, DISTINCT, ORDER BY, LIMIT or OFFSET. 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.
  3. 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 NULL where 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.
  4. 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 WHERE conditions on the outer table, NOT IN with NULLs, COUNT(*) versus COUNT(column) after outer joins, sums inflated by one-to-many joins, BETWEEN on timestamps that drops the last day, integer division, ambiguous grouping in permissive dialects, DISTINCT hiding a join problem, window frames that default to RANGE, 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 for LIMIT with a big OFFSET. Mark which are definite and which depend on data you have not seen.
  1. 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.

constraints
  • 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.
output format

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

Edit on GitHubReport a problem

use in

Hodios CLI
npx @hermes-hq/hodios install explain-sql-query --target claude-code
Agent Skills
npx skills add hermes-hq/hodios-dist --skill explain-sql-query -a claude-code
Add the Hodios marketplace (once)
claude plugin marketplace add hermes-hq/hodios-dist
Install the software-engineering plugin
claude plugin install hodios-software-engineering@hodios

The plugin brings every entry in this domain at once.

PromptPerformance

Optimise 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-query
PromptData exploration

Review 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-sql
PromptLearning to code

Explain 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-code
PromptData exploration

Answer 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-sql
RuleConventions

SQL 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-rules
PromptLearning to code

Explain 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