sql-query-explainer

SQL 查询解释器技能

此技能使用通俗语言解释 SQL 查询、发现优化机会，并帮助向非技术利益相关者说明数据逻辑。它还可以根据自然语言描述编写和记录新查询。

必需输入

• SQL（解释／优化／编写文档模式）——实际查询语句，最好注明所用方言（Postgres、BigQuery、Snowflake、MySQL……）；不同方言会影响语义和优化建议。
• 通俗描述的意图（编写模式）——数据需要回答什么问题，以及已知的表名和列名。如果没有架构信息，需明确说明假设，不得默默臆造。
• 可选但影响显著：EXPLAIN／EXPLAIN ANALYZE 输出和大致的表大小——这些信息可将通用建议转化为针对你的查询计划的建议。

模式

根据用户的请求判断所需模式：

1. 解释——将现有 SQL 转换为通俗易懂的语言
2. 优化——检查 SQL 的性能问题并提出改进建议
3. 编写——根据自然语言描述生成 SQL
4. 编写文档——生成数据字典或查询文档

---

模式 1：解释

收到 SQL 查询时，生成以下内容：

通俗易懂的摘要

[1–3 句话。此查询的作用是什么？会返回哪些数据？像向业务分析师而不是开发人员解释那样撰写。]

分步说明

将查询拆分为逻辑部分。对每个部分：

• 引用 SQL 子句
• 用通俗易懂的语言说明其作用
• 指出其中的复杂之处（例如窗口函数、子查询、CTE）

结果的形式

[描述输出的结构：“每位用户返回一行，包含 X、Y、Z 列。按 [字段] 降序排列。”]

需指出的潜在问题

• [此查询中的陷阱、边缘情况或隐含假设]
• [例如：“如果 LEFT JOIN 未找到匹配项，user_id 列中可能会包含 NULL”]

---

模式 2：优化

用户要求优化查询时，生成以下内容：

性能评估

总体评级：🟢 优化良好 / 🟡 仍有改进空间 / 🔴 存在重大问题

发现的问题

对每个问题：

问题 [N]：[简短名称，例如“连接列缺少索引”]

• 问题所在：[通俗说明]
• 影响原因：[对性能的影响，例如“对一个含 1,000 万行的表执行全表扫描”]
• 修复方法：

-- Before
[original snippet]

-- After
[improved snippet]

• 预期改进：[尽可能给出估算]

优化检查清单

• 是否使用了 SELECT *？（替换为指定列）
• JOIN／WHERE 列是否存在隐式类型转换？
• JOIN 或 WHERE 列是否缺少索引？
• 是否存在 N+1 模式（在循环中执行查询）？
• 是否使用了 DISTINCT，而 GROUP BY 会更快？
• 是否使用了窗口函数，而子查询会更清晰或更快？
• CTE 是否被重复使用或不必要地物化？
• 是否存在可改用 JOIN 的大型 IN() 列表？

---

模式 3：编写

收到自然语言描述时，生成 SQL 查询，然后使用模式 1 进行解释。

请用户确认：

• 数据库／方言（PostgreSQL / MySQL / BigQuery / Snowflake / SQLite / Standard SQL）
• 表名和列名（如果已知；否则使用 users、orders、user_id 等描述性占位符名称）
• 任何筛选、排序或聚合要求

生成：

1. 带内联注释的 SQL 查询
2. 通俗易懂的说明（采用模式 1 的格式）

---

模式 4：编写文档

用户要求为查询或表创建文档时：

查询文档

Query: [Name]
Purpose: [One sentence — what business question this answers]
Author: [If provided]
Last reviewed: [If provided]

Inputs:
  - Table: [table_name] — [what it contains]
  - Filter: [any WHERE conditions and their business meaning]

Output columns:
  | Column | Type | Description |
  |--------|------|-------------|
  | [name] | [type] | [plain English description] |

Assumptions:
  - [Any implicit assumptions the query makes]

Known limitations:
  - [Edge cases not handled, data quality dependencies, etc.]

---

输出格式

每种模式都采用相同且严谨的结构：

1. 一句话摘要 — 用业务语言说明此查询的作用（例如“按地区统计月收入，不包括退款”），先于任何 SQL 相关内容。
2. 逐步讲解或查询内容 — 根据模式而定：逐条子句加注释的解释（Explain）、重写后的查询，并对变更内容及原因进行对比说明（Optimise）、新查询及其假设（Write），或文档块（Document）。
3. 注意事项 — 说明适用于此查询的 NULL 行为、连接造成的行数膨胀、时区陷阱和索引影响，而非泛泛而谈。
4. 验证 — 提供一条简短的 SELECT，供用户运行以确认查询实现了摘要中所述的功能（比较前后的行数，或抽查某个条件）。

质量检查

• 使用通俗语言解释，避免 SQL 术语
• 优化建议包含优化前后的 SQL
• 编写的查询包含行内注释
• 说明输出结构（列、每行代表的粒度、排序方式）
• 标明非标准的方言特定语法

反模式

• 用伪代码复述 SQL，而不解释它做什么以及返回什么
• 提供优化建议，却没有优化前后的查询对比，或没有说明新查询为何更快
• 忽略 SQL 方言（为 MySQL 用户编写仅适用于 Postgres 的语法）
• 只说“看起来没问题”，却不分析正确性、性能或每行代表的粒度
• 另起炉灶重写查询，而不是解释或优化用户的查询

示例触发语句

• “解释这条 SQL 查询：[粘贴查询]”
• “优化这条运行缓慢的查询：[粘贴查询]”
• “编写一条 SQL 查询，用于[自然语言描述]”
• “为非技术利益相关者编写这条查询的文档”
• “为什么这条查询返回了意料之外的结果？”