SQL query explainer that walks through what a query returns, step by step, and spots logic bugs
A portable assistant for analysts, PMs and new engineers: paste a SQL query (and optionally the schema) and it explains in plain language what the query returns, in execution order, with a worked example, and flags likely logic bugs such as fan-out joins and NULL handling.
Agent in Data by AISkillHub Library
What it does
Inherited SQL is hard to read: nested subqueries, five joins, window functions, a WHERE clause that quietly turns a LEFT JOIN into an INNER JOIN. This assistant explains a query in the order the database logically evaluates it, shows a tiny worked example, and points out where the result might not be what the author intended.
**What it does**
- Asks for the SQL dialect (PostgreSQL, MySQL, SQL Server, BigQuery, Snowflake, SQLite or other) if it is not obvious. - Gives a **one-sentence summary** of what each output row represents (the grain), which is the most common source of misunderstanding. - Walks through the query in **logical order**: FROM and JOINs, WHERE, GROUP BY, HAVING, window functions, SELECT, DISTINCT, ORDER BY, LIMIT. Each CTE is explained separately first. - Builds a **mini worked example** with three to five made-up rows per table and shows the intermediate and final results. - Flags **likely bugs**: join fan-out that double-counts sums, LEFT JOIN filters in WHERE, NULL comparisons with `=`, NOT IN with NULLs, integer division, timezone and date boundary issues, non-deterministic ORDER BY with LIMIT, aggregates mixed with non-aggregated columns. - Optionally rewrites the query for readability (CTEs, aliases, comments) without changing results, and states any dialect-specific syntax used.
**When to use it**
- Reviewing a dashboard query before trusting its numbers - Onboarding to a new data warehouse - Learning SQL with real queries from your team
**What it will not do**
- It does not run queries or connect to your database. Performance advice is general unless you paste an execution plan. - It does not guess column meanings with confidence. If the schema is missing, it labels its assumptions about what columns contain. - It will not write queries that modify or delete data unless you explicitly ask, and then it adds a warning and suggests a transaction or a SELECT preview first.
**Example flag**
"`LEFT JOIN orders o ON ...` followed by `WHERE o.status = 'paid'`: the WHERE clause removes customers with no orders, so this behaves like an INNER JOIN. If you want to keep customers with no paid orders, move the condition into the ON clause."
How to use it
The same `assistants/sql-query-explainer/instructions.md` works in all three products. Pick one:
- **ChatGPT custom GPT:** Explore GPTs, then **Create**, then the **Configure** tab. Name it `SQL Explainer` and paste the file into **Instructions**. Upload (optional) your schema (DDL or a table and column list with descriptions) and a data dictionary, so explanations use the real meaning of columns. Never upload actual customer data. in the product's file or knowledge area. - **Claude Project:** create a project named `SQL Explainer`, paste the file into the project's custom instructions setting. Upload (optional) your schema (DDL or a table and column list with descriptions) and a data dictionary, so explanations use the real meaning of columns. Never upload actual customer data. in the product's file or knowledge area. - **Gemini Gem:** in the Gems manager create a **New Gem** named `SQL Explainer` and paste the file into **Instructions**. Upload (optional) your schema (DDL or a table and column list with descriptions) and a data dictionary, so explanations use the real meaning of columns. Never upload actual customer data. in the product's file or knowledge area. - **No setup option:** paste the whole file as the first message of a new chat in any of the three, then continue in that chat.
**Variables to fill before pasting:** `{{default_dialect}}` in the file (for example `PostgreSQL` or `BigQuery`). Leave it to be asked per query.
Test with one real example before sharing it with your team.
**Using it:** paste a query. Add `schema:` with the relevant tables if they are not in the uploaded files. Commands: `explain`, `example` (worked example only), `bugs` (only the review), `rewrite` (readable version).
Files
Save each file at the path shown, relative to your project root.