debugging-failed-data-quality-checks

失敗したデータ品質チェックのデバッグ

チェックの実行結果は、4 つの状態のいずれかで終了します。 まず状態を確認してください。問題の調査先がわかります。

ステータス	意味	確認する場所
failed	クエリが実行され、アサーションで不正なデータが見つかった	データ、またはアサーション自体
errored	クエリを実行できず、判定も行われなかった	エラーテキスト（データの問題ではありません）
skipped	対象が存在しない	テーブルまたはビューがまだ存在するかどうか
passed	アサーションが成立した	確認は不要

row_count と freshness のチェックでは、failed_row_count ではなく observed_value を判定します。 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 です。エラーになった実行結果にも付くことがあるため、まず status を確認してください。

保持期間の経過により、30 日後に compiled_query は消去されます。 それより古い実行については、チェックを再実行してください。

ステップ 2：失敗した行を確認する

posthog:execute-sql で compiled_query を実行します。 compiled_query が空の場合、再生するものはありません。保持期間によって削除されたか、ゲート付きの実行でビューの定義を読み取れなかった可能性があります。 何かを報告する前に、どの行に一致したかを確認してください。 失敗の原因は、データが正しくないか、アサーションが正しくないかのどちらかです。 どちらなのかは行を見ればわかります。

audited_staged_refresh が true の場合、クエリは公開済みテーブルを読み取りません。 WITH 句にビューの定義を保持し、ビューのソーステーブルを現在読み取ります。 実行後にソースが変更されている可能性があるため、行や件数が実行時と異なる場合があります。 現在のクエリが 0 行を返しても、リフレッシュに問題がなかったことの証明にはなりません。 実行時の 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 とともに表示されるメッセージは 2 つあります。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：失敗しているマテリアライズドビューの特定