SQL Query Explainer

1. Overview

This process takes a SQL statement and, when supplied, the raw text of the query’s result. It produces a clear, plain‑language description of what the query is intended to do and, if results are provided, a concise interpretation of those results in the context of the query’s purpose.

2. Business Value

Rapid understanding – Enables analysts, managers, and non‑technical stakeholders to grasp the intent of a query without dissecting the code.
Improved documentation – Generates readable explanations that can be added to data dictionaries, reports, or knowledge bases.
Error spotting – By restating the query’s purpose, discrepancies between intent and result become obvious early.
Knowledge sharing – New team members can quickly learn how existing queries work, accelerating onboarding and collaboration.

3. Operational Context

When to run –
- During code review of a newly written or inherited query.
- When preparing documentation or presentation material that references a query.
- When a colleague asks for a quick interpretation of a query and its output.
Who uses it – Data Analysts, Business Analysts, Data Engineers, Product Managers, and anyone who needs to communicate query intent to a broader audience.
How often – On an ad‑hoc basis whenever a query’s purpose or result needs to be explained.

4. Inputs

Name / Label	Type	Details Provided
SQL Query	Text	The complete SQL statement to be explained. Include line breaks and any comments exactly as written.
Query Result (optional)	Text	The raw textual output produced when the query is executed (e.g., a console table, CSV‑style rows, or any printable format). If omitted, the process will only generate the query explanation.

Only the items listed above are required for a single run of this process.

5. Outputs

Name / Label	Contents	Formatting Rules
Query Explanation	A plain‑language description of what the query does, covering the main operation, source tables, joins, filters, aggregations, ordering, and any limits.	Written in neutral, professional tone; use short paragraphs or bullet points; avoid technical jargon unless essential.
Result Summary (generated only when a result is supplied)	A concise interpretation of the output, including the number of rows returned, key metrics or trends observed, and any noteworthy patterns in relation to the query’s intent.	Begin with a brief sentence summarizing the overall outcome, followed by bullet points for specific observations. Use the same tone as the Query Explanation.

6. Detailed Plan & Execution Steps

Confirm Input Presence
- Verify that the SQL Query field is not empty.
- Record whether Query Result is present.
Basic Syntax Check
- Ensure the query contains one of the primary keywords: SELECT, INSERT, UPDATE, DELETE.
- If none are found, stop and return an error message: “SQL query does not contain a recognizable operation.”
Identify Core Components
- Determine the main operation (e.g., “retrieves”, “adds”, “modifies”, “removes”).
- List all source tables mentioned after FROM and any additional tables introduced by JOIN.
- Capture any filtering conditions after WHERE.
- Note grouping (GROUP BY), aggregation functions (COUNT, SUM, AVG, etc.), ordering (ORDER BY), and row limiting (LIMIT, TOP).
- If the query uses a Common Table Expression (WITH), treat the CTE as an intermediate step and focus on the final SELECT/INSERT/UPDATE/DELETE.
Compose Query Explanation
- Start with “This query [verb] …”.
- Mention the primary table(s) and their purpose (if recognizable from the name).
- Summarize filters, groupings, and aggregations in everyday language (e.g., “for each product category, it calculates the total sales”).
- Include ordering or limiting information if present.
- Keep the description to two‑to‑four sentences or a short bullet list.
If Query Result Is Provided – Process Result a. Detect Header Row – Assume the first line contains column names separated by common delimiters (comma, tab, or multiple spaces). b. Count Rows – Count the number of subsequent lines that contain data. c. Identify Key Columns – Look for numeric columns (contain only digits, optional decimal point) and date‑like columns (match typical date patterns). d. Summarize –
- State total rows returned.
- Highlight the most extreme values (e.g., highest, lowest) for numeric columns, up to three examples each.
- Note any obvious patterns (e.g., “most rows have a status of ‘Active’”). e. Handle Large Results – If more than 100 rows are present, summarize only counts and top‑5 rows based on the first numeric column.
Assemble Final Output
- Place the Query Explanation first.
- If a Result Summary exists, insert it directly after the explanation, separated by a blank line.
Return Results
- Provide the two output items in the format defined in Section 5.
- If any validation step failed, return an error status with a clear message and no partial explanation.

7. Validation & Quality Checks

Coverage Check – Ensure the explanation references every table name appearing in the query.
Filter Inclusion – Confirm that any WHERE conditions are reflected in the plain‑language description.
Aggregation Mention – If the query uses COUNT, SUM, AVG, MIN, or MAX, those functions must appear in the explanation.
Result Alignment – Verify that the number of rows reported in the Result Summary matches the actual count of data lines.
Numeric Highlight Accuracy – Cross‑check that the “highest” and “lowest” values reported truly belong to the identified column.
Error Handling – If any required component is missing (e.g., empty query) or the result format cannot be parsed, output an error message and halt further processing.

8. Special Rules / Edge Cases

Situation	Handling
Multiple SQL statements	Process only the first statement; note in the explanation that additional statements were ignored.
Placeholders (`?`, `:param`)	Mention that the query contains parameters whose values are not known, and therefore the explanation will refer to “the supplied parameter(s)”.
Empty Result Set	State “The query returned zero rows.” and omit further numeric summarisation.
Result Larger Than 100 Rows	Summarise row count only, and list the first five rows as examples.
Non‑tabular Result (e.g., single scalar value)	Include the scalar value directly in the Result Summary as the key outcome.
Syntax Errors Detected	Abort processing and return an error message: “Unable to interpret the query due to syntax issues.”
Result Contains Mixed Delimiters	Attempt to split on commas first; if that yields a single column, fallback to tabs or multiple spaces. If still ambiguous, note “Result format could not be reliably parsed; summary omitted.”
Complex Subqueries or Nested CTEs	Focus the explanation on the overall intent of the outermost query; optionally note the presence of subqueries without dissecting them.
Query Uses Database‑Specific Functions (e.g., `DATEPART`, `STRING_AGG`)	Mention the function’s purpose in plain language (e.g., “extracts the month from a date”).

9. Example

Input

SQL Query

SELECT c.region, SUM(s.amount) AS total_sales
FROM customers c
JOIN sales s ON c.customer_id = s.customer_id
WHERE s.sale_date BETWEEN '2023-01-01' AND '2023-03-31'
  AND c.status = 'Active'
GROUP BY c.region
ORDER BY total_sales DESC
LIMIT 5;

Query Result

region,total_sales
North,125430.75
West,112300.00
South,98750.50
East,84520.20
Central,63210.00

Output

Query Explanation This query retrieves the total sales amount for each active customer region during the first quarter of 2023. It joins the customers table with the sales table on the customer identifier, filters sales to dates between January 1 and March 31 2023, and includes only customers whose status is “Active.” The results are grouped by region, ordered from highest to lowest sales, and limited to the top five regions.
Result Summary
- The query returned 5 rows, each representing a region.
- North had the highest sales at $125,430.75.
- Central recorded the lowest sales at $63,210.00.
- All reported regions are active customers, and the sales figures reflect Q1 2023 totals.

Appendix A – FAQ

Q1. What if the query contains a WITH clause (CTE)? A: The explanation will treat the CTE as an internal step and focus on the final SELECT/INSERT/UPDATE/DELETE statement. The presence of the CTE will be noted (“The query first defines a temporary result set …”).

Q2. Can this process explain INSERT, UPDATE, or DELETE statements? A: Yes. The explanation will describe the data modification intent, the target table, any conditions that restrict the rows, and any columns being set or values being inserted. No result summary is produced for data‑modifying statements unless a result set (e.g., RETURNING clause) is supplied.

Q3. My query returns a single numeric value. How will it be summarised? A: The Result Summary will state the scalar value directly, e.g., “The query returned a single value: 42.”

Q4. The result contains dates formatted as YYYYMMDD. Will the summary interpret them? A: Dates will be mentioned as they appear. If a date column is identified, the summary may note the earliest and latest dates present.

Q5. What if the query result is larger than 100 rows? A: Only the total row count will be reported, along with the first five rows as examples.

Q6. My query includes a parameter placeholder like :start_date. A: The explanation will reference the placeholder as “the supplied start date parameter.” No concrete value will be inferred.

Q7. The query uses a database‑specific function I don’t recognize. A: The function will be described in plain language based on its name (e.g., “calculates the month part of a date”). If the function is truly unknown, the explanation will note “a custom function.”

Q8. I received an error while running the query. Can this process still explain it? A: No. If the SQL statement cannot be parsed because of syntax errors, the process returns an error message and does not generate an explanation.

Appendix B – Glossary

Term	Definition
SELECT	Retrieves data from one or more tables.
INSERT	Adds new rows to a table.
UPDATE	Modifies existing rows in a table.
DELETE	Removes rows from a table.
FROM	Indicates the source table(s) for the query.
JOIN	Combines rows from two tables based on a related column.
WHERE	Filters rows based on a condition.
GROUP BY	Aggregates rows that share a common value in specified columns.
HAVING	Filters groups created by `GROUP BY`.
ORDER BY	Sorts the result set.
LIMIT / TOP	Restricts the number of rows returned.
CTE (Common Table Expression)	A temporary named result set defined using `WITH` that can be referenced later in the query.
Subquery	A query nested inside another query.
Aggregation Function	Functions like `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` that compute a single result from multiple rows.
Parameter Placeholder	A symbol such as `?` or `:name` that will be replaced with a value at execution time.
Scalar Result	A single value (e.g., `SELECT COUNT(*) FROM …`).

Appendix C – Style Guide for Query Explanations

Start with the verb that matches the operation
- SELECT → “retrieves”, “shows”, “lists”.
- INSERT → “adds”, “creates”.
- UPDATE → “modifies”, “updates”.
- DELETE → “removes”, “deletes”.
Mention source tables early
- “from the customers table” or “from the sales and products tables”.
Summarise filters in plain terms
- WHERE status = 'Active' → “including only active records”.
- sale_date BETWEEN '2023-01-01' AND '2023-03-31' → “for sales that occurred in Q1 2023”.
Explain aggregations without jargon
- SUM(s.amount) → “the total sales amount”.
- COUNT(*) → “the number of records”.
Describe grouping and ordering succinctly
- “grouped by region” → “calculates totals for each region”.
- “ordered by total_sales descending” → “shows the highest‑selling regions first”.
Limit and top‑N
- “LIMIT 5” → “returns only the top five results”.
Use short sentences (≤ 20 words) and active voice.
Avoid technical symbols (;, commas in list of columns) unless they are part of a literal value.
Consistent tone – neutral, professional, and objective.
Examples of Good vs. Bad

Bad (too technical)	Good (plain language)
“The query selects `c.region` and `SUM(s.amount)` from `customers` c inner join `sales` s on `c.customer_id = s.customer_id` …”	“This query lists each region and the total sales amount for that region.”
“Filters where `s.sale_date` is between `2023‑01‑01` and `2023‑03‑31` and `c.status` = `Active`.”	“It includes only sales from the first quarter of 2023 and customers who are active.”
“Groups by `c.region` and orders by `total_sales` descending, limiting to 5 rows.”	“The results are grouped by region, sorted from highest to lowest sales, and only the top five regions are shown.”

Tips for Consistency

Use the exact table names as they appear in the query; do not rename them.
When a column name includes an underscore, read it as a space (e.g., total_sales → “total sales”).
If a column or table name is ambiguous, add a brief clarifier in parentheses (e.g., “sales (the transaction table)”).

Additional Notes

Copy‑paste accuracy – Ensure the entire SQL statement, including line breaks and any comments, is included in the SQL Query input. Missing parts can lead to incomplete explanations.
Result formatting – Provide the query result exactly as displayed by your database client (e.g., CSV, tab‑delimited, or plain table). Consistent delimiters help the process parse the data correctly.
Large datasets – For very large result sets, the summary will be limited to counts and the first five rows to keep the output concise.
Parameterised queries – If placeholders are present, the explanation will note that the query expects external values and will describe the condition generically.

Benefit	Business Impact
Speed	Analysts redirect time from writing to deeper analysis
Clarity	Stakeholders understand results without a data background
Consistency	Uniform phrasing across reports builds trust
Accuracy	Direct extraction of figures removes manual entry errors

From SQL Query to Plain Narrative

SQL Query Explainer

1. Overview

2. Business Value

3. Operational Context

4. Inputs

5. Outputs

6. Detailed Plan & Execution Steps

7. Validation & Quality Checks

8. Special Rules / Edge Cases

9. Example

Appendix A – FAQ

Appendix B – Glossary

Appendix C – Style Guide for Query Explanations

Additional Notes

Explain Query

SQL Query Input

The Data Translation Gap

Turning Numbers Into Business Insight

How the SQL Query Explainer Works

What You Gain

Benefit Summary

Consistent Narratives Drive Better Decisions

Ready to Automate?