auditing-warehouse-view-health

审计数据仓库视图健康状况

此技能会对数据仓库中的物化视图（已物化的保存查询）进行全项目审计，查看哪些视图失败，哪些视图已物化但未使用。适用于用户希望了解视图健康状况概览，而非深入排查某一项故障的情况。

同一底层端点（data-warehouse-data-health-issues-retrieve）还会报告来源、同步、批量导出和转换问题。来源和同步的健康状况由 auditing-warehouse-source-health 负责。目标位置（批量导出）和转换归其他产品负责——如果审计中发现这些问题，请一并指出，但应转交相关团队，而不是在此进行诊断。

何时使用此技能

• “我的哪些视图出了问题？”／“为什么这个物化视图会失败？”
• “有没有物化视图在浪费计算资源？”
• HogQL 或架构变更后的视图健康状况检查
• 基于物化视图的仪表板数据过时或报错

可用工具

工具	用途
data-warehouse-data-health-issues-retrieve	一次性获取整个数据管道中所有失败或降级的项目
view-list	所有已保存查询／物化视图及其状态和 latest_error
view-run-history	特定物化视图的运行历史记录
warehouse-suggestions-list	PostHog 尚未处理的弃用／物化／认证建议（如有）

将 data-health-issues 结果筛选为 materialized_view 类型，以用于此次审计。如果需要查看活跃故障摘要之外的信息（未失败的视图、物化标记、最近查询信息），请使用 view-list；如需查看特定视图的运行记录，请使用 view-run-history。

视图“问题”的定义

对于数据健康端点返回的结果，此审计关注五种类别中的一种：

type	触发条件	典型紧急程度
materialized_view	DataWarehouseSavedQuery.is_materialized=true, status=Failed	中

每个条目都包含 id、name、type、status、error、failed_at 和 url。

此端点返回的其他类别不在此技能的范围内：

• source／external_data_sync → auditing-warehouse-source-health
• destination（批量导出）→ 由批量导出／数据管道产品负责
• transformation（HogFunction）→ 由 CDP／数据摄取团队负责

请注意，数据健康端点只报告_活跃故障_。对于视图，它不会标记：

• 有错误的非物化视图（只报告物化视图）
• 健康但未使用的物化视图（每次运行都会消耗计算资源）——请参阅步骤 4

工作流

步骤 1 — 一次性拉取

调用 data-warehouse-data-health-issues-retrieve，并保留 materialized_view 条目。

如果没有视图问题，请告知用户其物化视图运行正常，然后结束。不要凭空捏造问题。

步骤 2 — 分诊故障

物化视图故障通常与来源无关——视图故障一般是视图本身的 HogQL 或数据问题（语法错误、缺少表引用、类型不匹配）。对于每个失败的视图，请指出 error 并定位出错的查询。如果用户想查看故障记录，请使用 view-run-history。

如果 error 以 Not published: 开头，说明这不是查询问题。该视图未通过数据质量检查，因此刷新被暂缓。请转交给 debugging-failed-data-quality-checks。

步骤 3 — 呈现审计结果

生成一份按优先级排列的报告。不要直接输出原始 JSON，应使用易读的格式：

## Materialized view health — 2 issues

### 🟠 Materialized views (2)
- monthly_revenue — view failed (syntax error in HogQL: 'FORM' instead of 'FROM')
- active_users_30d — view failed (missing table reference)

Both are HogQL issues in the view definitions — independent of your sources. Want me to open one?

步骤 4 — 按需检查活跃故障之外的问题

如果有 warehouse-suggestions-* 工具，请从 PostHog 的建议开始。 调用 warehouse-suggestions-list，并设置 status=proposed。PostHog 根据读取用量计算这些建议：

• deprecate 建议会指出无人读取的物化视图。接受建议后，该视图会在数据目录中标记为已弃用。视图仍会继续刷新，因此仍会消耗计算资源。如需停止这项开销，请在用户确认后使用 view-unmaterialize 取消物化。
• materialize 建议会指出读取频率足够高、物化后可节省计算资源的视图。接受建议后，将按建议的刷新模式和间隔启用物化。

在进行任何手动审计之前，先展示这些建议。按照 reviewing-warehouse-suggestions 技能来解释、修改、接受或驳回这些建议。

未使用的物化视图： 调用 view-list。物化视图每次运行都会消耗存储和计算资源。如果某些视图标记为已物化，但近期没有被查询，请将其列为清理候选项（可通过 view-list 获取相关数据；使用 view-unmaterialize 取消物化）。

只有在用户明确要求进行更全面的审计时，才执行这项额外检查。

步骤 5 — 提出下一步建议

审计结束时，明确交接下一步，例如：“要我打开 monthly_revenue 并修复 HogQL 吗？” 切勿在审计过程中擅自应用修复；编辑视图或取消其物化之前，务必先获得明确确认。

重要说明

• 审计为只读操作。 未经明确确认，切勿在审计流程中调用破坏性工具（例如 view-unmaterialize、view-delete）。
• 无结果 = 状态正常。 不要在空审计中编造假设性问题。“未发现视图问题”就是恰当的答复。
• 视图故障通常仅影响自身。 与数据源故障不同，物化视图失败很少引发连锁问题——通常只是该视图中的查询问题。不要暗示存在更广泛的服务中断。
• 此处不涵盖数据源、同步、目标位置和转换。 它们共用数据健康端点，但属于其他审计或产品——应转交处理，不要在此诊断。