authoring-data-quality-checks

编写数据质量检查

检查是针对某个仓库表、视图或 HogQL 目录指标的一项断言。它会编译为仅计数的 HogQL 查询，并且在未发现失败行时通过，与 dbt test 类似。失败行不会被存储；只会存储计数和编译后的查询，因此如需查看问题行，必须自行重新运行已存储的查询。

row_count 是个例外。观测到的计数在配置的最小值和最大值范围内时，它就会通过，因此返回的 failed_row_count 为 null，存储的查询会返回单个计数，而不是问题行。请根据观测到的计数进行判断，而不是查找匹配行。

读取通过 SQL（system.information_schema.data_quality_*）进行；写入和运行则通过数据质量 MCP 工具进行。

开始编写前：先查看

两个查询可以帮你避免两个最常见的错误——重复创建检查，以及检查不存在的列。

-- What is already covered?
SELECT name, subject_name, column_name, check_type, config, severity, last_status
FROM system.information_schema.data_quality_checks
WHERE subject_name = 'orders'

-- What columns are there, and what do they mean?
SELECT column_name, data_type, description
FROM system.information_schema.columns
WHERE table_name = 'orders'

重新创建一个字节完全相同的检查不会造成问题，因为检查以主题、类型、列和配置的指纹作为键，因此创建相同检查会执行 upsert。创建一个 近似 重复的检查则会带来问题：读取结果的人会收到双倍的噪声。如果某个现有检查的断言接近正确但有误，请编辑该检查。更新会保留其身份和历史记录；主题由 URL 固定。若编辑后的断言与另一项检查重复，更新会被拒绝。

选择检查

优先选择少数几个确实能发现实际回归的检查，而非面面俱到。一个有二十项无人查看的检查的模型，不如只有三项但能发现有意义问题的模型。

可优先考虑以下检查，大致按顺序排列：

• 对下游联接和筛选所依赖的列使用 not_null。 这是价值最高的一项检查。联接键为空会悄无声息地丢弃行。
• 对模型所声明的粒度使用 unique。 如果 orders 每个订单只有一行，就明确声明这一点。
• 对外键使用 relationships。 可发现上游变更后悄然停止匹配的联接。
• 对下游逻辑会据此分支的状态和类别列使用 accepted_values。
• 对任何同步数据的时间戳列使用 freshness。 可发现已停止运行的数据管道，而逐行检查都无法做到这一点。
• 已知合理范围时，使用 row_count 边界。 有助于发现同步数据被截断。
• 仅在以上检查都无法表达该不变量时，才使用 custom_sql，例如跨列算术（select 1 from orders where total != subtotal + tax）。查询返回的每一行都会计为失败。

请调用 posthog:data-quality-check-types，查询每种类型的准确配置架构，不要猜测。

一套工具适用于所有类型的主题。请调用 posthog:data-quality-subjects，查询你可以读取的表、视图和指标，然后将其提供的 subject_type 和 id 分别作为 subject_type 和 subject_uuid 传入 posthog:data-quality-check-create。只有标记为 editable 的主题才能配置检查；其他主题仍可作为 relationships 检查的目标。之后通过检查自身的 ID 来操作检查：-update、-delete、-run 和 -results 均不需要主题参数。

PostHog 表上的检查

events、persons 和 groups 与其他主体一样支持检查：传入 subject_type: "posthog_table"，并使用 ID posthog:data-quality-subjects。所有检查 类型都适用于这些表，relationships 也可以将其中一张表作为目标。

这些表很大，因此在为它们编写检查之前，请考虑设置 lookback_hours。它会根据表自身的时间列限制检查读取的行数：events 使用 timestamp，persons 和 groups 使用 created_at。该列表示每行首次出现的时间，而非最后一次更改的时间。 如果不设置，检查会读取整张表；这是允许的，有时也是你想要的做法——对 events.uuid 使用不设时间范围的 unique 检查，能得出窗口化检查无法得出的结论。如果检查超出 ClickHouse 的执行预算，会返回 errored 状态及相应消息；通常添加时间窗口即可解决。

对于 relationships 检查，lookback_hours 限制检查的行数，to_lookback_hours 限制用于查找匹配项的目标行数。请谨慎设置第二个参数：目标时间窗口过窄，会导致行因时间过久而失败，而非因数据有误而失败。

custom_sql 不接受 lookback_hours。请自行在查询中添加时间筛选条件，否则查询会读取整张表。

这些表不会像同步触发源表那样触发检查，因此它们的检查按计划运行，默认每天一次。使用 posthog:data-quality-check-schedule 更改计划。

目录指标上的检查

只有已保存 HogQLQuery 定义的指标才支持检查。Markdown、趋势、漏斗、事件序列以及没有定义的指标均不支持。指标可以返回任意数量的行和列。

创建 custom_sql 检查，并将 column_name 留空。将 {metric} 恰好作为一个关系包含一次：

SELECT *
FROM {metric}
WHERE orders < 100

检查会查询所属指标当前已保存的输出。示例假设该输出包含 orders 列。每一行返回结果都表示失败；返回零行则通过。可以直接查询 {metric}，也可以通过子查询查询。指标检查 SQL 不能定义 CTE，包括嵌套 CTE 和标量 WITH 绑定。指标定义中仍支持 CTE 和已保存的参数。检查中不接受其他占位符。

请使用指标的 Tests 选项卡，或使用 posthog:data-quality-check-create 并设置 subject_type: "metric"。目录通过名称标识指标，而检查通过 UUID 指定指标。将 subject_type=metric 传递给 posthog:data-quality-check-types，它只会提供 Custom SQL。

保存时会验证 SQL 组合，但不会执行 SQL。运行检查以验证列名和结果。每次运行都会重新加载已保存的指标：如果编辑操作移除了检查所用的列，下次运行就会报错。请修正检查 SQL，或恢复预期的指标输出。

严重程度和触发条件

严重程度是对后果的判断，而不是对置信度的判断。如果失败意味着下游数字不应被信任，就使用 error——这类失败会将主体标记为 failing 并发送通知。对于值得指出、但今天没人会采取行动的问题，使用 warn。不确定时，warn 是更安全的默认值：一个误报的 error 检查会让所有人都不再理会警告。

表和视图触发条件： 主体的数据发生变化时，检查就会运行：物化视图的检查会作为刷新的一部分运行（团队启用门禁后，如果错误级别的检查失败，该次刷新就不会发布）；源表的检查会在每次同步完成后运行；普通视图的检查会在其 DAG 运行时执行。DAG 之外的视图检查仅会按需运行。

主体计划： 指标和 PostHog 表没有可用于触发检查的数据变更事件，因此检查会按计划运行。保存某个主体的第一项检查时，会为该主体的所有检查创建一个已启用的每日计划。Tests 选项卡可用于更改间隔或关闭自动运行。仍可手动运行。计划检查使用最新定义作者的访问权限；如果无法使用，则回退到创建者的权限。手动运行使用发起用户的访问权限。底层表和附加表必须可读。

Temporal 管理每个指标的运行频率和暂停状态。已暂停的计划没有下一次执行时间。如果计划响应不可用，请先重新加载，再重试编辑；编辑可能已经成功。自动运行会跳过重叠任务，并且只会在 15 分钟内补跑错过的执行。

禁用或删除所有检查后，计划偏好设置仍会保留。删除指标会移除其计划。

验证你写的检查

创建检查、运行一次、查看结果。没人运行过的检查只是一种猜测。

1. posthog:data-quality-check-create
2. posthog:data-quality-check-run — 返回一个套件运行结果
3. 轮询 system.information_schema.data_quality_check_runs（或 posthog:data-quality-check-results）以获取结果

首次运行得到 failed 结果最值得关注：要么你发现了真实的坏数据，要么断言有误。从运行结果中获取 compiled_query，使用 posthog:execute-sql 执行，并查看它实际匹配了哪些内容，然后再报告任何问题。该 compiled_query 来自 posthog:data-quality-check-results；第 3 步中的 information_schema 轮询不会返回它。errored 结果绝不意味着数据有问题——查询根本无法运行，通常是列名拼写错误或主体已不存在。要进一步调查失败或出错的运行，请使用 debugging-failed-data-quality-checks。

使用数据源前，先判断其状态

如果分析依赖数据仓库中的表或视图，请先检查其判定结果：

SELECT subject_name, health, checks_total, checks_failing, last_run_at
FROM system.information_schema.data_quality_health

• failing — 错误级别的检查发现了坏数据。请在回答中说明；不要悄悄使用该数据。
• erroring — 检查无法运行。数据可能没有问题，但无人监控。
• warn — 只有警告级别的检查失败。可以使用，但值得提及。
• healthy — 检查已运行且全部通过。
• unknown / absent — 没有检查，或没有检查运行过。没有发现失败，并不能证明数据健康。

如需查看判定结果的历史记录，system.information_schema.data_quality_check_runs 包含近期执行记录及其状态、失败行数和错误信息。对于指标检查，失败行数描述的是断言结果，而不是标量指标值。打开 Tests 选项卡中的失败行查询，检查当前违反该检查的行。

相关内容

• setting-up-data-catalog — 数据的 含义：指标、信任标记和关系。
• querying-posthog-data — 这些查询遵循的架构发现规则和 HogQL 规则。
• debugging-failed-data-quality-checks — 检查失败或出错的原因，以及门禁未发布的刷新。