debugging-snowflake-queries

调试 Snowflake 查询

系统地调试 Snowflake SQL：复现故障、分类问题、隔离最小故障单元、核实粒度和联接，然后再重写查询。

适用场景

• 诊断 Snowflake 错误，例如 SQL compilation error、invalid identifier、object does not exist、ambiguous column、类型转换失败、权限失败或超时
• 调试能够运行但返回错误计数、重复行、空结果、看起来过时的数据或不可能的百分比的查询
• 调查性能问题，例如扫描耗时过长、仓库问题或意外开销很大的联接
• 审查临时 SQL 查询，并说明如何使其正确且可复现

不适用场景

• 模板或应用层的 SQL 生成故障，且实际并未调试 Snowflake SQL
• 一般业务调查，主要任务是回答问题，而非调试查询本身

工作流

1. 复现出错的原始查询，或重建等效的最小查询。
2. 修改 SQL 前先对问题分类：
   • 编译／名称解析
   • 权限／环境
   • 类型／转换／NULL 语义
   • 联接／粒度／结果正确性
   • 性能／扫描／仓库
   • 上游数据过时或不完整
3. 将查询缩减为最小故障组件：
   • 每次检查一个 CTE
   • 每次检查一个联接
   • 每次检查一个计算表达式
   • 每次检查一个筛选条件
4. 先核实对象是否存在、模式以及准确的列名，不要想当然。
5. 明确说明每个输入和中间结果的粒度。
6. 在每个联接边界检查计数和 NULL 比例。
7. 如果查询在逻辑上有误但语法有效，请用有针对性的反例或诊断查询证明故障模式。
8. 只有在隔离根本原因后，才重写完整查询。

核心规则

• 优先使用最小诊断查询，而不是推测性地重写查询。
• 让每个调试步骤都可证伪：每个查询只回答一个问题。
• 不要仅因两个表有名称相似的 ID，就假设它们可以联接。
• 在证实并非如此之前，将行数激增视为粒度不匹配。
• 遇到零行时，先检查筛选条件、时间范围或联接键，再归咎于数据缺失。
• 遇到异常百分比时，先检查分母范围，再怀疑算术。
• 在 dbt 宏之外工作或可能存在环境歧义时，使用完全限定名称。
• 涉及后端镜像时，检查软删除列以及数据新鲜度／摄取时间戳。
• 对于大型事实表，先收紧日期筛选条件并检查扫描情况，再运行范围较广的诊断。

参考资料

按需加载以下参考资料：

• references/debugging-playbook.md 用于端到端工作流、诊断查询模板以及如何缩小故障范围。
• references/error-taxonomy.md 用于将常见 Snowflake 错误消息对应到可能原因和后续检查项。
• references/result-correctness-checklist.md 用于查询能够运行但结果看起来有误的情况：重复、数据丢失、分母错误、数据过时。
• references/query-patterns-and-failure-modes.md 用于查看与数据仓库无关的常见故障模式实例及其修正方法。

预期输出

返回调试答案时：

1. 用一句话说明可能的根本原因。
2. 展示最少量的诊断证据。
3. 提供修正后的查询或确切的修复方法。
4. 说明仍然存在的假设，尤其是有关粒度、环境或上游数据新鲜度的假设。