debugging-failed-data-quality-checks

调试失败的数据质量检查

一次检查运行会以四种状态之一结束。 请先查看状态，因为它决定了问题所在：

状态	含义	查看位置
failed	查询已运行，断言发现了异常数据	数据或断言本身
errored	查询无法运行，因此未进行任何判定	错误文本（绝不是数据问题）
skipped	目标对象已不存在	表或视图是否仍然存在
passed	断言成立	无

row_count 和 freshness 检查判断的是 observed_value，而不是 failed_row_count。 row_count 检查失败表示计数超出了范围。 freshness 检查失败表示最新一行的时间早于限定时间。

何时使用此技能

• 某项检查或某个目标对象显示为 failed 或 errored，用户想了解原因
• 用户想查看某项检查匹配到的行
• 某个物化视图的最新运行显示以 Not published: 开头的错误
• 刷新后视图仍在提供旧数据，且启用了数据质量门禁
• 另一个技能（authoring-data-quality-checks 或 auditing-warehouse-view-health）发现检查失败或视图受阻，并将问题移交给此技能

可用工具

工具	用途
posthog:data-quality-check-results	查看某项检查的近期运行记录，包括 compiled_query、error 和运行时配置
posthog:execute-sql	重新运行某次运行记录的 compiled_query，以查看失败的行
posthog:data-quality-check-run	立即运行一项检查
posthog:data-quality-check-update	修复断言或更改其严重级别
view-get	查看视图的定义和状态
view-run-history	查看视图的物化运行记录及其错误
view-run	再次物化视图

要查找失败的检查，可查询 system.information_schema.data_quality_checks，筛选 last_status IN ('failed', 'errored')；也可查询 system.information_schema.data_quality_health，查看某个目标对象的判定结果。

工作流

步骤 1：查看运行记录

针对这项检查调用 posthog:data-quality-check-results。 查看最新一次运行记录中的：

• status 和 error
• check_config 和 check_severity：本次运行断言的内容，可能与当前检查的设置不同
• compiled_query：用于查询失败行的 HogQL。对于 row_count，它会改为返回计数，因此应根据 observed_value 判断该检查。
• audited_staged_refresh：如果为 true，表示本次运行属于发布前对刷新进行的门禁审计。errored 状态的运行也可能带有此字段，因此请先查看 status。

保留策略会在 30 天后清除 compiled_query。 对于更早的运行记录，请重新运行检查。

第 2 步：查看失败的行

使用 posthog:execute-sql 运行 compiled_query。 compiled_query 为空表示没有可重放的内容：保留策略已清除这些内容，或者受门控的运行无法读取视图定义。 在报告之前，先查看它匹配到了什么。 失败的原因只有两种：数据有问题，或者断言有误。 查看这些行即可判断是哪一种。

当 audited_staged_refresh 为 true 时，查询不会读取已发布的表。 它会在 WITH 子句中保存视图定义，并读取视图的源表当前数据。 源数据可能已在本次运行后发生变化，因此这些行和计数可能与运行时不同。 现在返回零行的查询，并不能证明刷新时数据没有问题。 请与运行中的 failed_row_count 对比。

第 3 步：查看出错的运行

出错的运行并未判断数据。 根据错误文本进行匹配：

错误文本	原因和修复
The staged files could not be read, so this data was not audited.	门控无法在发布前访问刷新数据。刷新会在没有判定结果的情况下发布。请重新运行该视图。
Metric checks cannot audit staged data.	受门控的刷新中包含指标检查。它会按自身的计划运行。
The check query returned no rows.	聚合查询没有返回任何内容。请重新运行检查；如果再次出现，请报告此问题。
A check that reads another subject needs an initiator or author…	自动运行的 custom_sql 或 relationships 检查没有可供其代表运行的用户。手动运行即可成功。编辑检查断言会将编辑者设为其作者。
HogQL 或 ClickHouse 错误	列名拼写错误、类型不匹配，或者查询超时。请修正配置，或添加 lookback_hours。

有两条消息会伴随 skipped：The subject was deleted. 和 The subject no longer resolves. 表或视图已不存在。 请删除该检查，或将其指向替代对象。

第 4 步：了解刷新被阻止的情况

当团队启用“Block materialization on failing checks”时，物化视图的错误级别检查会在每次发布刷新之前运行。 如果有检查失败：

• 视图的运行会显示以 Not published: 开头的错误（参见 view-run-history）。
• 视图的上一版本会继续提供查询服务。
• 本次运行中，同一 DAG 下游的视图会被跳过。
• 视图的计划不会暂停。 下次计划刷新时会再次运行检查。

警告级别的检查永远不会阻止刷新。

第 5 步：恢复

修复原因，然后验证结果：

1. 修复上游数据，或使用 posthog:data-quality-check-update 修正断言。 如果故障确实存在，但不应阻止刷新，请将 severity 改为 warn。
2. 对于刷新被阻止的视图，请调用 view-run 再次将其物化。 否则，请调用 posthog:data-quality-check-run。
3. 再次读取 posthog:data-quality-check-results，并确认最新一次运行已通过。

重要说明

• 不要只为让检查通过就更改检查的严重级别或断言。 请先与用户确认。
• errored 绝不是数据不良的证据，而空表上的 passed 也不是数据良好的证据。
• 检查会针对其主体报告结果，但 custom_sql 查询可以读取其他表。 在归咎于主体之前，请先阅读查询。

相关内容

• authoring-data-quality-checks：编写和选择检查
• auditing-warehouse-view-health：查找失败的物化视图