数据库测试故障排除

数据 社区

技能解读

当前原文的自动摘译,尚未人工审校。

要求

代理:任何(只读诊断)、构建器(如果应用修复) 使用的工具:bash(运行 altimate-dbt 命令)、read、glob、edit、altimate_core_semantics、altimate_core_column_lineage、altimate_core_ Correct、altimate_core_fix、sql_fix

何时使用此技能

在以下情况下使用: dbt 模型无法编译或构建 测试失败 模型产生错误或意外的数据 构建缓慢或超时

铁律

在不了解测试失败原因的情况下,切勿修改测试以使其通过。修复所有错误,而不仅仅是报告的错误。修复特定问题后,运行完整的dbt build。如果其他模型失败——即使是错误报告中没有提到的模型——也要修复它们。您的工作是让项目处于完全工作状态。切勿将错误视为“预先存在”或“超出范围”而忽略。

第 1 步:健康检查

如果doctor失败,请先修复环境。常见问题: 未找到 Python → 重新安装或设置 --python-path dbt-core 未安装 → pip install dbt-core 没有 dbt_project.yml → 目录错误 缺少软件包 → 如果 packages.yml 存在但 dbt_packages/ 不存在,则运行 dbt deps

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
数据
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@AltimateAI · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
Python
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

01
第 1 步:健康检查

如果`doctor`失败,请先修复环境。常见问题: 未找到 Python → 重新安装或设置 `--python-path` dbt-core 未安装 → `pip install dbt-core` 否 `dbt_project.yml` → 目录错误 缺少软件包 → 如果 `packages.yml` 存在但 `dbt_packages/` 不存在,请运行 `dbt deps`

02
第 2 步:对错误进行分类

错误类型·症状·跳转到编译错误·Jinja/YAML解析失败·references/compilation-errors.md运行时/数据库错误·SQL执行失败·references/runtime-errors.md测试失败·测试返回失败行·references/test-failures.md错误数据·模型构建但数据不正确·下面的步骤3

03
步骤3b:离线SQL分析

在访问数据库之前,离线分析已编译的 SQL: 快速修复工具 — 在错误类型明确时使用这些工具:`altimate_core_fix` 最适合编译错误(名称错误、对象丢失)。 `sql_fix` 最适合运行时错误(数据库告诉你出了什么问题)。当第一次修复无法解决问题时,使用`altimate_core_correct`进行迭代多轮修正。常见发现:

04
步骤3c:错误的数据诊断——深度数据探索

当模型构建但产生错误结果时,错误几乎总是存在于数据假设中,而不是 SQL 语法中。您必须探索实际数据才能找到它。常见的错误数据根本原因: 连接扇出:如果行数高于预期,则连接键不唯一 — 使用`SELECT key, count(*) ... GROUP BY 1 HAVING count(*) > 1` 检查 INNER JOIN 中缺少行:如果行数低于预期,请切换到 LEFT JOIN 并检查 NULL 连接键

05
第 4 步:检查上游

大多数错误都是从上游模型级联而来:读取父模型。单独构建它们。查询父数据——不要假设它是正确的:

06
第 5 步:修复并验证

应用修复后:始终使用`--downstream`进行构建以捕获级联影响。然后使用数据查询验证修复 - 不要只信任构建:

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。