authoring-data-quality-checks

データ品質チェックの作成

チェックとは、データウェアハウスのテーブル、ビュー、または HogQL カタログメトリクスに対する 1 つのアサーションです。カウントのみを返す HogQL クエリにコンパイルされ、dbt test と同様に、失敗した行が 0 件の場合に合格します。失敗した行は保存されません。保存されるのは件数とコンパイル済みクエリのみです。そのため、該当する行を確認するには、保存されたクエリを自分で再実行してください。

例外は row_count です。設定した最小値／最大値の範囲内に観測件数が収まっている場合に合格するため、failed_row_count は null になり、保存されたクエリは該当する行ではなく、その件数のみを返します。一致する行を探すのではなく、観測件数を確認して判断してください。

読み取りには SQL（system.information_schema.data_quality_*）を使用し、書き込みと実行にはデータ品質 MCP ツールを使用します。

作成する前に確認する

次の 2 つのクエリを実行すれば、よくある 2 つのミス、すなわちチェックの重複と、存在しないカラムのチェックを防げます。

-- 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'

バイト単位で同一のチェックを再作成しても、問題のない no-op です。チェックは対象、タイプ、カラム、設定のフィンガープリントをキーとしているため、同一のチェックを作成すると upsert されます。_ほぼ_重複するチェックは問題になります。結果を読む人のノイズが倍増するためです。既存のチェックのアサーションが近いものの正しくない場合は、既存のチェックを編集してください。更新してもチェックの ID と履歴は維持され、対象は URL によって固定されています。別のチェックのアサーションと重複する編集は拒否されます。

チェックの選び方

網羅的にチェックを追加するのではなく、実際のリグレッションを検出できるチェックを少数選びましょう。誰も読まない 20 個のチェックがあるモデルより、意味のある失敗を検出する 3 個のチェックがあるモデルのほうが優れています。

まずは、おおむね次の順で検討してください。

• 下流の結合やフィルタリングが依存するカラムに対する not_null。 最も価値の高いチェックです。結合キーが null だと、行が気付かれないまま除外されます。
• モデルが定義する粒度に対する unique。 orders が注文ごとに 1 行なら、そのように指定してください。
• 外部キーに対する 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 を、posthog:data-quality-check-create の subject_type と subject_uuid に渡してください。editable とマークされた対象にのみチェックを設定できます。それ以外の対象も、relationships チェックの対象にはできます。その後は、チェック自体の ID で操作します。-update、-delete、-run、-results に対象を指定する必要はありません。

PostHog テーブルのチェック

events、persons、groupsには、ほかの対象と同様にチェックを設定できます。subject_type: "posthog_table"と、posthog:data-quality-subjectsが返すIDを指定してください。すべてのチェックタイプが使用でき、relationshipsではこれらのテーブルをターゲットとして指定することもできます。

これらのテーブルは大きいため、チェックを作成する前にlookback_hoursを検討してください。これは、各テーブル固有の時刻列によってチェックが読み取る行を制限します。eventsではtimestamp、personsとgroupsではcreated_atです。created_atは、最後に変更された日時ではなく、最初に確認された日時です。これを指定しない場合、チェックはテーブル全体を読み取ります。これは許可されており、場合によっては意図した動作です。events.uuidに対するウィンドウ指定なしのuniqueチェックは、ウィンドウを指定したチェックでは得られない情報を示します。ClickHouseの実行予算を使い切ったチェックは、メッセージとともにerroredを報告します。通常はウィンドウを追加すれば解決します。

relationshipsチェックでは、lookback_hoursがチェック対象の行を制限し、to_lookback_hoursが一致する行を検索する対象を制限します。2つ目の値は慎重に設定してください。ターゲットのウィンドウが狭いと、行が誤っているためではなく、古いために失敗することがあります。

custom_sqlではlookback_hoursを指定できません。クエリに自分で時刻フィルターを追加してください。追加しない場合、テーブル全体が読み取られます。

同期によってソーステーブルが更新される場合と異なり、これらのテーブルをトリガーするものはありません。そのため、チェックはデフォルトで毎日、スケジュールに従って実行されます。posthog:data-quality-check-scheduleで変更できます。

カタログのメトリクスに対するチェック

保存済みのHogQLQuery定義があるメトリクスのみ、チェックに対応しています。Markdown、Trends、Funnels、イベントシリーズ、定義のないメトリクスは対応していません。メトリクスは任意の数の行と列を返すことができます。

column_nameを空にしてcustom_sqlチェックを作成します。{metric}をリレーションとして正確に1回含めてください。

SELECT *
FROM {metric}
WHERE orders < 100

このチェックは、所有元のメトリクスに現在保存されている出力をクエリします。この例では、その出力にorders列があることを前提としています。返された各行が失敗となり、行が0件の場合は合格です。{metric}は直接クエリすることも、サブクエリを介してクエリすることもできます。メトリクスチェックのSQLでは、ネストされたCTEやスカラーのWITHバインディングを含め、CTEを定義できません。メトリクス定義内のCTEと保存済みパラメーターは引き続き使用できます。チェックでは、ほかのプレースホルダーは使用できません。

メトリクスの「Tests」タブを使用するか、subject_type: "metric"を指定してposthog:data-quality-check-createを使用してください。カタログではメトリクスを名前で指定しますが、チェックではUUIDで指定します。subject_type=metricをposthog:data-quality-check-typesに渡すと、Custom SQLのみが提示されます。

保存時にはSQLの組み立てが検証されますが、実行はされません。列名と結果を確認するには、チェックを実行してください。実行のたびに保存済みのメトリクスが読み込まれます。編集によってチェックで使用している列が削除されると、次回の実行はエラーになります。チェックのSQLを修正するか、想定されるメトリクス出力に戻してください。

重大度とトリガー

重大度は結果に関する判断であり、確信度に関する判断ではありません。失敗によって下流の数値を信頼できなくなる場合は、error を使用してください。このような失敗では対象が failing になり、通知が送られます。今日すぐに誰かが対応するほどではないものの、表面化させる価値がある事柄には warn を使用してください。迷った場合は、warn を選ぶほうが安全です。誤報を出す error チェックがあると、すべて無視されるようになります。

テーブルとビューのトリガー： チェックは、対象のデータが変更されたときに実行されます。マテリアライズドビューのチェックは更新の一環として実行され（チームがゲートを有効にすると、重大度が 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 — 重大度が error のチェックで不正なデータが見つかりました。回答でその旨を伝え、黙って使用しないでください。
• erroring — チェックを実行できませんでした。データに問題がない可能性はありますが、監視されていません。
• warn — 失敗したのは重大度が warn のチェックのみです。使用できますが、その旨に触れてください。
• healthy — チェックが実行され、合格しました。
• unknown／なし — チェックがないか、実行されたチェックがありません。失敗がないことは、健全性の証明にはなりません。

判定の履歴を確認するには、system.information_schema.data_quality_check_runs にある最近の実行結果で、ステータス、失敗した行数、エラーを確認できます。メトリクスのチェックでは、失敗した行数はスカラーのメトリクス値ではなく、アサーションの結果を表します。現在チェックに違反している行を確認するには、Tests タブから失敗行クエリを開いてください。

関連項目

• setting-up-data-catalog — データの 意味：メトリクス、信頼マーク、リレーションシップ。
• querying-posthog-data — これらのクエリで使用するスキーマ検出と HogQL のルール。
• debugging-failed-data-quality-checks — チェックが失敗またはエラーになった理由と、ゲートで公開されなかった更新。