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 を使います。

ビューの「問題」とみなされるもの

data-health エンドポイントが報告する項目のうち、この監査で対象とするのは次の5カテゴリのうち1つです。

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／データ取り込み側が担当

data-health エンドポイントが報告するのは、現在発生中の障害 だけです。ビューに関して、次の項目は報告されません。

• エラーがある非マテリアライズドビュー（マテリアライズドビューのみ報告されます）
• 正常だが使用されていないマテリアライズドビュー（実行のたびにコンピュートリソースを消費します）— 手順4を参照

ワークフロー

手順1 — 一括取得

data-warehouse-data-health-issues-retrieve を呼び出し、materialized_view の項目を抽出します。

ビューの問題がなければ、ユーザーにマテリアライズドビューは正常であると伝え、そこで終了します。問題を捏造しないでください。

手順2 — 障害のトリアージ

マテリアライズドビューの障害は、通常、ソースとは無関係です。ビューの障害は、ビュー自体の HogQL またはデータの問題（構文エラー、テーブル参照の欠落、型の不一致）です。失敗している各ビューについて、error の内容を示し、問題のあるクエリを指摘してください。ユーザーが障害の経緯を確認したい場合は、view-run-history を使います。

Not published: で始まる error は、クエリの問題ではありません。ビューのデータ品質チェックに失敗したため、更新が保留されています。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 — アクティブな障害以外も確認する（依頼された場合）

PostHog の提案から始めます。warehouse-suggestions-* ツールが利用可能な場合は、status=proposed を指定して warehouse-suggestions-list を呼び出します。PostHog は読み取り状況から提案を算出します。

• deprecate の提案では、誰も読み取っていないマテリアライズドビューが示されます。これを承認すると、データカタログでビューが非推奨としてマークされます。ビューの更新は続くため、コンピューティングコストは発生し続けます。そのコストをなくすには、ユーザーの確認後に view-unmaterialize でビューのマテリアライズを解除します。
• materialize の提案では、マテリアライズするとコンピューティングコストを削減できるほど頻繁に読み取られているビューが示されます。これを承認すると、提案された更新モードと間隔でマテリアライズが有効になります。

手動監査を行う前に、これらの提案を提示します。説明、変更、承認、または却下を行う際は、 reviewing-warehouse-suggestions スキルに従ってください。

未使用のマテリアライズドビュー： view-list を呼び出します。マテリアライズドビューは、実行のたびにストレージとコンピューティングコストが発生します。マテリアライズ済みとしてマークされているものの、最近クエリされていないビューがあれば、クリーンアップ候補として提示します（データは view-list で取得できます。マテリアライズを解除するには view-unmaterialize を使用します）。

この追加チェックは、ユーザーがより広範な監査を明示的に依頼した場合にのみ実行してください。

ステップ 5 — 次の対応を提案する

監査の最後に、明確に次の対応へ引き継ぎます。例：「monthly_revenue を開いて HogQL を修正しましょうか？」監査から自律的に修正を適用してはいけません。ビューの編集やマテリアライズ解除の前に、必ず明示的な確認を得てください。

重要な注意事項

• **監査は読み取り専用です。**明示的な確認なしに、監査のフローで破壊的なツール（例：view-unmaterialize、view-delete）を呼び出してはいけません。
• **空の結果は正常です。**空の監査結果に仮定上の問題を付け加えないでください。「ビューの問題は見つかりませんでした」は適切な回答です。
• **ビューの障害は通常、個別に収まります。**ソースの障害とは異なり、マテリアライズドビューの障害が連鎖することはまれです。通常はそのビュー内のクエリの問題です。より広範な障害が発生しているかのように示唆しないでください。
• **ソース、同期、宛先、変換はここでは対象外です。**これらも同じデータヘルスエンドポイントを使用しますが、別の監査や製品の対象です。診断せず、適切な担当先へ案内してください。