データ品質とデータコントラクト

「品質が悪い」を測定可能な述語に分解する

分析基盤で最も高くつく障害は、パイプラインがエラーで止まる障害ではありません。エラーを一切出さずに、間違った数字を正しい顔で下流へ配り続ける障害です。売上KPIが実は二重計上されている、特徴量のNULLが増えてモデル精度が静かに劣化している——気づくのは往々にして経営会議やモデルの本番事故の後です。この「壊れた成功（silently wrong）」を捕まえるには、「品質が悪い」という主観をデータに対する検証可能な述語へ落とし込む必要があります。

品質は一枚岩ではなく、独立に測れるディメンションに分解して扱うのが定石です。核になる四つを、それぞれ「何を測る述語か」として押さえます。

• 完全性（completeness）: 必要な行・値が欠けていないか。列単位のNULL率、期待した行数に対する充足率、期待キー集合に対する欠損（source に居る顧客IDが gold に居ない）。
• 一意性（uniqueness）: 主キー・自然キーが重複していないか。count(*) と count(distinct key) の差が重複行数そのものになる。分析基盤では結合や再取り込みで容易に重複が混入するため、集計の桁を狂わせる最大要因になりやすい。
• 妥当性（validity）: 値が定義された型・値域・許容集合・参照整合を満たすか。amount >= 0、status が {active, churned, trial} のいずれか、外部キーが親テーブルに存在する、といった制約への適合。
• 鮮度（freshness）: データが十分に新しいか。最新パーティションのイベント時刻や最終ロード時刻が、いま何分・何時間遅れているか。値そのものは正しくても、遅れていれば意思決定には使えない。

分析基盤ならではの注意は、これらが**バッチの規模（数億〜数十億行）**に対する集計統計として測られる点です。行単位の制約（1行が値域を満たすか）ではなく、列・テーブル単位の集計量（NULL率・重複数・分布・鮮度）が期待範囲かを見る。1行の妥当性を1件ずつ弾くのはOLTPの制約の仕事で、ここで問うのは「バッチ全体として異常が混ざっていないか」です。取引系（OLTP）と分析系（OLAP）でデータモデルとアクセスが正反対になる背景は /data-engineering/olap-vs-oltp/ に通じます。

期待値テスト：品質をパイプラインの関門にする

ディメンションを述語に書けたら、それを期待値（expectation） として宣言し、パイプラインの一タスクとして自動実行します。期待値テストとは「このデータはこうあるべき」という表明を、閾値付きで機械検査する仕組みです。素朴には次のような宣言の集合になります。

# orders テーブルへの期待値（宣言的に列挙する）
expectations:
  - column: order_id
    expect: unique                 # 一意性
  - column: order_id
    expect: not_null               # 完全性（キーの欠損禁止）
  - column: amount
    expect: between
    min: 0
    max: 1000000                   # 妥当性（値域）
  - column: status
    expect: in_set
    values: [active, churned, trial]   # 妥当性（許容集合）
  - table: orders
    expect: row_count_between
    min: 100000
    max: 5000000                   # 完全性（件数の異常検知）
  - table: orders
    expect: freshness_within
    hours: 3                       # 鮮度

これを DAG に組み込み、変換の各段の後で検査します。設計上の要点は三つです。

第一に、閾値は絶対値だけでなく相対（対前日・移動平均比）で持つ。「行数が10万〜500万」の固定窓では、事業成長や季節変動で誤検知・見逃しが増えます。「行数が過去7日中央値の±30%以内」「NULL率が前日から急増していない」といった基準線（baseline）からの逸脱で見るほうが、静かな劣化を捉えられます。分布の急変検知（あるカテゴリ値の比率が跳ねた等）も同じ発想です。

第二に、違反時の挙動を明示的に選ぶ。選択肢は大きく三つあります。

キー重複や鮮度切れのような下流の集計を確実に狂わせる違反は fail fastで止め、汚れの混入が一部行に限られるなら隔離して正常分を供給する。ここで停止・隔離が安全に成立する前提が、対象区間を冪等に作り直せる設計です。検査で止めた区間を修正後に再実行しても重複や破壊が起きない——この土台が無いと fail fast は「止めたら復旧できない」罠になります。品質検査を DAG の関門として組み込む位置づけと冪等性の関係は /data-engineering/etl-elt-pipelines/ で扱った運用の続きです。

第三に、検査結果自体をメトリクスとして蓄積する。合否だけでなくNULL率・重複数・鮮度の時系列を残せば、閾値が破られる前の「じわじわ悪化」を可視化でき、異常検知の基準線にもなります。

データコントラクト：生産者と消費者の明示的な合意

期待値テストは「消費側が受け取ったデータを検査する」防御でした。しかし根本原因の多くは生産側にあります。アプリ開発チームが users テーブルの列名を変えた、型を string から int に変えた、status の意味をこっそり変えた——生産者にとっては自チームのDBの都合ですが、その変更はCDCやETLを通じて下流の数百資産へ波及します（変更が下流へ伝播する経路は /data-engineering/cdc-log-based/ の通り）。消費側でいくら検査しても、これは受け取ってから気づく事後対応にすぎません。

データコントラクト（data contract） は、この非対称を正すための、生産者と消費者の明示的な合意です。データを「たまたま覗けるDBのテーブル」ではなく、**約束された仕様を持つ製品（API に近いもの）**として扱い、生産者に供給責任を負わせます。コントラクトに載る典型的な項目は次のとおりです。

# データコントラクトの骨子（生産者が公開し、消費者が依存する）
dataset: orders
owner: team-checkout          # 生産責任の所在
schema:                       # スキーマ（列・型・NULL可否）
  - name: order_id
    type: string
    nullable: false
    unique: true              # 一意キーの表明
  - name: amount
    type: decimal(12,2)
    nullable: false
    constraint: ">= 0"        # 妥当性の表明
  - name: status
    type: string
    enum: [active, churned, trial]
sla:                          # 品質・供給のSLA
  freshness: "<= 3h"          # 鮮度保証
  completeness: "email NULL率 <= 1%"
  availability: "毎日 06:00 JST までに当日パーティション提供"
semantics:                    # 意味の定義（誤解を防ぐ）
  amount: "税込・返品控除後の確定金額（通貨は常にJPY）"
version: 2.1.0                # 変更管理のためのバージョン

コントラクトの本質は、期待値テストで書いた品質述語を「消費側の防御」から「生産側の約束」へ移すことです。同じ「order_id は一意」「鮮度3時間以内」という表明でも、消費側で検査すれば受け取ってからの発見、コントラクトに書けば生産者が守るべき契約になり、破れば生産側の CI が赤くなる。責任の所在が源泉に移るのが決定的な違いです。

破壊的スキーマ変更を出荷前に弾く

コントラクトが最も効くのは、破壊的変更（breaking change）の予防です。変更を「下流を壊すか否か」で分類し、壊す変更をマージ前に機械的に検出して弾く——これがコントラクトを CI に組み込む中心的な価値です。互換性は大きく二方向で考えます。

• 後方互換（backward compatible）: 新スキーマで書いたデータを、旧スキーマを前提とする消費者がそのまま読めるか。列の追加（デフォルト付き）や列挙値の追加は、既存消費者が新列・新値を無視すれば読めるので後方互換。
• 前方互換（forward compatible）: 旧スキーマで書いたデータを、新スキーマを前提とする消費者が読めるか。任意列の削除などがこちらに関わる。

分析基盤で事故になる典型的な破壊的変更は次のものです。

CI での防ぎ方は、新旧コントラクトの差分を取り、互換性ルールに照らして破壊的変更を検出することです。生産側リポジトリのプルリクエストで、提案スキーマと現行スキーマを突き合わせ、「列 email の削除は後方互換を破る」と判定されたらマージをブロックする。破壊的変更をどうしても入れる場合は、バージョニングと段階移行に従わせます。

破壊的変更を安全に出す手順（例：amount を税抜→税込へ意味変更）
  1. 新フィールド amount_incl_tax を追加（旧 amount は残す）＝後方互換
  2. コントラクトのバージョンを上げ、旧 amount を非推奨(deprecated)と告知
  3. 消費者に移行猶予を与える（リネージで依存資産を洗い出し個別通知）
  4. 全消費者の移行を確認してから旧 amount を削除
  → 「いきなり破壊」を「追加→猶予→撤去」の三段に分解する

ここで互換性を後付けする土台を提供するのがテーブルフォーマットです。列に不変のフィールドIDを振ることで、列の追加・改名・削除を既存ファイルを書き換えずに安全に行える——スキーマ進化の内部機構は /data-engineering/lakehouse-iceberg-delta/ の通りで、コントラクトが「してよい変更／だめな変更」の方針を決め、テーブルフォーマットがそれを安全に施工する機構を担う、という分業になります。

まとめ

• データ品質は主観ではなく測定可能なディメンションに分解する。完全性（欠損）・一意性（重複）・妥当性（型・値域・参照）・鮮度（遅れ）を、テーブルに対する検証可能な述語として定義する。
• 分析基盤では行単位でなく**バッチ全体の集計統計（NULL率・重複数・分布・鮮度）が期待範囲かを問う。狙いは例外落ちではなく「壊れた成功」（成功を装った異常値）**の捕捉。
• 期待値テストは品質述語を閾値付きの表明として DAG の関門で自動実行する。閾値は基準線からの相対逸脱で持ち、違反時はfail fast／隔離／警告を明示的に選ぶ。停止・再実行が安全なのは冪等設計が前提。
• データコントラクトは生産者と消費者の明示的合意で、スキーマ＋SLA＋意味の三点セット。品質述語を「消費側の防御」から**「生産側の約束」**へ移し、責任の所在を源泉に置く。
• 破壊的スキーマ変更（列削除・改名・型変更・意味変更）は、新旧コントラクトの差分を互換性ルールで判定してマージ前に弾く。どうしても入れる変更は追加→非推奨→撤去の段階移行とバージョニングに従わせる。
• コントラクトが変更の方針を決め、テーブルフォーマットのスキーマ進化がそれを安全に施工する。品質・コントラクト・リネージを束ねて、上流の一存で下流が壊れる事故を構造的に断つ。