OliverOuyang/sql-validate-and-export

SQL 分段验证、结果导出与智能分析

核心理念

SQL 查询在复杂环境中容易出错（字段名错误、表引用错误、JOIN 膨胀等）。本 skill 通过分段验证、逐步合并的方式，确保最终结果可靠，并自动导出为 CSV 文件。最后，从数据和用户角度进行智能分析，预判用户可能追问的问题并提前给出答案。

这个流程模拟了资深数据分析师的工作习惯：先摸清数据，再逐步拼装，最后主动讲故事和提前回答追问——而不是把一张表甩给用户让他们自己看。

执行流程

Phase 1: 解析与元数据验证

1. 读取 SQL 文件，解析出涉及的所有表和字段
2. 调用 Dataphin MCP 验证元数据：
   • mcp__sh_dp_mcp__get_dp_table_meta 获取每张表的字段列表和类型
   • 逐一核对 SQL 中引用的字段是否存在于正确的表中
   • 检查字段类型是否与使用方式匹配（如 string 类型用于数值计算需注意隐式转换）
3. 记录发现的问题，分类为：
   • 致命错误：字段不存在、表名错误 → 必须修复
   • 警告：类型隐式转换、可能的 NULL 值 → 提示用户

Phase 2: 自动修复

如果发现错误，在用户确认后自动修复：

• 字段归属错误 → 修正表别名（如 t2.field → t1.field）
• 子查询缺字段 → 补充 SELECT 列表
• 子查询多余字段 → 移除无用字段
• 拼写错误 → 修正字段名
• GROUP BY / ORDER BY 与 SELECT 不一致 → 同步修正

修复后重新验证，确保所有引用正确。

Phase 3: 分段执行与验证

按照从简单到复杂的顺序执行，每步验证结果合理性：

Step 1: 单表验证

• 对每张基础表单独执行简单聚合查询（加 LIMIT）
• 检查：数据量级是否合理、关键字段值分布、是否有大量 NULL

Step 2: 两表 JOIN 验证

• 按 SQL 中的 JOIN 顺序，逐步添加表
• 检查：JOIN 后记录数是否膨胀、关键指标是否与单表结果可对账

Step 3: 完整查询执行

• 执行完整 SQL（保留 LIMIT 以防数据量过大）
• 交叉验证：各维度汇总是否等于上一步的总计

Phase 4: 结果导出

验证通过后：

1. 执行不带 LIMIT 的完整查询（如果数据量在 10000 条以内）
2. 将结果解析并写入 CSV 文件
3. 文件命名规则：{SQL文件名}_{YYYYMMDD_HHMM}.csv
   • 例如：贷前指标_20260407_1430.csv
   • 如果 SQL 不是来自文件，使用用户提供的名称或查询主题

Phase 5: 智能分析与预判追问

导出完成后，从数据视角和用户视角两个维度自动生成分析：

5.1 数据视角分析

基于查询结果自动识别：

• 漏斗瓶颈：哪一步筛选过滤掉最多数据，占比多少
• 异常波动：日间/维度间的异常偏差（>2σ或环比>20%）
• 分支贡献：OR/UNION 等多分支逻辑中，各分支的独立贡献和重叠率
• 趋势判断：时间序列数据的趋势方向和稳定性
• 边界风险：接近阈值的条件（如 <=30 的条件中大量数据集中在 25-30）

5.2 用户视角预判追问

根据查询的业务语义，提前回答用户最可能追问的 3-5 个问题：

| 问题类型 | 示例 | 生成方法 | |---------|------|---------| | 量级合理性 | "这个数跟预期比是多还是少？" | 对比同类历史查询或全表占比 | | 条件敏感度 | "如果把阈值从 30 改成 60，人数会变多少？" | 从单表验证的分布数据中估算 | | 分支差异 | "A 分支和 B 分支的用户重叠多少？" | 从最终合并逻辑中计算交集 | | 时间趋势 | "这个数是在涨还是在跌？" | 对时间维度做趋势判断 | | 下钻需求 | "能不能按渠道/产品拆分看？" | 识别 SQL 中未使用但可用的维度字段 |

5.3 输出格式

分析结果以结构化方式输出：

### 关键发现
- [发现1]：一句话结论 + 数据支撑
- [发现2]：...

### 预判追问 Q&A
**Q1: [用户可能问的问题]**
A: [基于数据的回答]

**Q2: ...**
A: ...

查询提交与轮询

使用 Dataphin MCP 异步查询：

提交: mcp__sh_dp_mcp__submit_dp_query → 获取 taskId
轮询: mcp__sh_dp_mcp__get_dp_query_status → 间隔 10s+

• 多个独立查询（如单表验证）应并行提交，提高效率
• 有依赖关系的查询（如需要上一步结果判断后再决定下一步）串行执行

结果合理性检查清单

每步执行后，自动检查以下项目：

| 检查项 | 方法 | 异常标准 | |--------|------|---------| | 记录数膨胀 | JOIN 前后对比 | JOIN 后 > 单表记录数 × 1.05 | | NULL 占比 | count 对比 | 关键维度 NULL > 10% | | 数值范围 | min/max/avg | 超出业务常识（如金额为负、比率 >100%） | | 维度覆盖 | distinct count | 缺少预期的维度值 | | 汇总可对账 | 分维度 sum vs 总计 | 差异 > 0.01% |

CSV 导出格式

• 编码：UTF-8 with BOM（确保 Excel 打开中文不乱码）
• 分隔符：逗号
• 第一行为列名（使用 SQL 中的 AS 别名）
• 数值保留原始精度，不做格式化
• 导出路径：与 SQL 文件同目录，或用户指定目录

异常处理

• 查询超时：使用 mcp__sh_dp_mcp__kill_dp_query 终止，缩小日期范围或加更多过滤条件后重试
• 权限不足：使用 mcp__sh_dp_mcp__apply_dp_table_permission 申请权限
• 表不存在：使用 mcp__sh_dp_mcp__get_dp_tables_by_path 搜索正确路径
• 结果超过 10000 条：提示用户是否分批导出或增加聚合粒度

输出给用户的信息

每个 Phase 完成后，输出简洁的中间结果摘要：

• Phase 1: 表结构验证结果（通过/发现N个问题）
• Phase 2: 修复内容清单（如有）
• Phase 3: 每步的关键数据指标（记录数、核心指标值、合理性判断）
• Phase 4: CSV 文件路径和数据概览（行数、列数、关键统计量）
• Phase 5: 关键发现（漏斗瓶颈、异常波动）+ 预判追问 Q&A（3-5 个）