SQL Query Explainer

SQL Query Explainer Skill

This skill explains SQL queries in plain language, identifies optimisation opportunities, and helps communicate data logic to non-technical stakeholders. It also writes and documents new queries from natural language descriptions.

Required Inputs

• The SQL (Explain/Optimise/Document modes) — the actual query, ideally with the dialect named (Postgres, BigQuery, Snowflake, MySQL…); dialect changes both semantics and the optimisation advice.
• The intent in plain words (Write mode) — what question the data should answer, plus table/column names if known. Without a schema, assumptions get stated, never silently invented.
• Optional but transformative: EXPLAIN/EXPLAIN ANALYZE output and rough table sizes — turns generic advice into advice about your query plan.

Modes

Detect which mode the user needs based on their request:

1. Explain — Translate existing SQL into plain English
2. Optimise — Review SQL for performance issues and suggest improvements
3. Write — Generate SQL from a natural language description
4. Document — Produce a data dictionary or query documentation

Mode 1: Explain

When given a SQL query, produce:

Plain English Summary

[1–3 sentences. What does this query do? What data does it return? Write as if explaining to a business analyst, not a developer.]

Step-by-Step Walkthrough

Break the query into logical sections. For each section:

• Quote the SQL clause
• Explain what it does in plain English
• Flag any complexity (e.g. window functions, subqueries, CTEs)

What the Result Looks Like

[Describe the shape of the output: "Returns one row per user, with columns for X, Y, Z. Ordered by [field] descending."]

Potential Issues to Flag

• [Gotchas, edge cases, or implicit assumptions in this query]
• [e.g. "This will include NULLs in the user_id column if the LEFT JOIN finds no match"]

Mode 2: Optimise

When asked to optimise a query, produce:

Performance Assessment

Rate overall: 🟢 Well-optimised / 🟡 Some improvements possible / 🔴 Significant issues

Issues Found

For each issue:

Issue [N]: [Short name, e.g. "Missing index on join column"]

• What it is: [Plain explanation]
• Why it matters: [Performance impact — e.g. "Full table scan on a 10M row table"]
• Fix:

-- Before
[original snippet]

-- After
[improved snippet]

• Expected improvement: [Estimate if possible]

Optimisation Checklist

• SELECT * used? (Replace with specific columns)
• Implicit type conversions on JOIN/WHERE columns?
• Missing indexes on JOIN or WHERE columns?
• N+1 patterns (queries inside loops)?
• DISTINCT used where GROUP BY would be faster?
• Window functions used where a subquery would be clearer/faster?
• CTEs re-used or materialised unnecessarily?
• Large IN() lists that could use a JOIN instead?

Mode 3: Write

When given a natural language description, generate the SQL query and then explain it using Mode 1.

Ask the user to confirm:

• Database/dialect (PostgreSQL / MySQL / BigQuery / Snowflake / SQLite / Standard SQL)
• Table and column names (if known; otherwise use descriptive placeholder names like users, orders, user_id)
• Any filters, sorting, or aggregation requirements

Produce:

1. The SQL query with inline comments
2. Plain English explanation (Mode 1 format)