設計データ契約の作成 は何をしますか？
使用するタイミング
- 上流（サービス、イベント、API、ファイル）が下流パイプラインにデータを供給しており、その変更が静かにパイプラインを破損する可能性がある場合
- プロデューシングチーム/システムとウェアハウスとの間のインターフェースを定義する場合
- データ取り込み境界でスキーマ/品質の適用を追加する場合
- 単一のdbtプロジェクト内での内部モデル間変更には使用しないでください（代わりにテスト+
handling-schema-evolutionを使用）
契約で指定するもの
- スキーマ: フィールド、型、null許容性、許容値
- セマンティクス: 各フィールドの意味、単位/粒度
- 保証: 鮮度/SLA、ボリュームの期待値、キーの一意性
- 所有権: 誰がプロデュースしているか、連絡先
- バージョン管理 + 変更ポリシー: 破壊的変更がどのように伝達されるか
ワークフロー
- [ ] 契約をバージョン管理された、チェックインされたスキーマとして記述する（暗黙の知識ではなく）
- [ ] 取り込み境界で契約を適用する（到着時に検証する）
- [ ] 変更を分類する：追加的（安全） vs 破壊的（新しいバージョンが必要）
- [ ] 違反があった場合、拒否/隔離し、プロデューサに警告する
- [ ] 破壊的変更を事前にバージョン管理し伝達する
- 明示的かつバージョン管理可能にする。 契約をコードとして（JSON Schema、Avro/Protobufスキーマ、またはYAML仕様）パイプラインの隣に保存し、APIと同じようにレビューします。
- 境界で適用する。 到着した受信データを契約に対して検証し、違反はロードする代わりに拒否または隔離します。
- 変更を分類する。 追加的/オプションフィールドは後方互換性あり。フィールドの削除、名前変更、型/null許容性の厳格化は破壊的 → 新しいバージョンが必要。
- プロデューサに即座に（静かに下流でなく）失敗を知らせる。
パターン
JSON Schemaとしての契約（取り込み時に適用）:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["order_id", "amount", "ordered_at"],
"properties": {
"order_id": { "type": "string" },
"amount": { "type": "number", "minimum": 0 },
"ordered_at": { "type": "string", "format": "date-time" },
"coupon": { "type": ["string", "null"] }
},
"additionalProperties": false
}
適用ポイント — 各レコードを取り込み時に検証し、失敗を quarantine 位置に理由とともにルーティングし、プロデューシングチームに警告します。これにより、下流での静かな破損が、発生源で即座に制御された信号に変わります。
スキーマレジストリ（Kafka/Avro）— 公開時に互換性（BACKWARD）を適用し、プロデューサが互換性のないスキーマを送信できないようにします。
よくある落とし穴
- 契約をドキュメントのみにする — コードで適用されないと、契約は乖離し静かに破損します。
- ウェアハウスの深部で適用する — 境界で違反を捕捉し、悪いデータが拡散する前に防ぎます。
- バージョン管理がない — すべての変更が緊急事態になります。適切にバージョン管理し、段階的に廃止します。
- 厳密性が必要なときに
additionalPropertiesを制限しない — 予期しないフィールドがすり抜けます。適切な場合は false に設定します。 - 所有者がいない — 拒否されたバッチに連絡する相手がおらず、パイプラインが停滞します。
- 破壊的変更にリードタイムがない — バージョン管理されたスキーマと廃止ウィンドウを通じてプロデューサ/コンシューマ間で調整します。