データパイプラインのデバッグ
使用すべきタイミング
- パイプラインジョブが失敗した、または出力データが誤っている/欠けている/重複している。
- ダッシュボードが古い、またはメトリクスがソースと一致しない。
- ステークホルダーが不一致を報告し、原因を特定する必要がある。
- ツール固有の実行エラーが既に
debugging-dbt-runs/debugging-airflow-pipelinesでカバーされている場合は、そちらを先に使用してください（そちらから始め、データ正しさのインシデントには本スキルを使用）。
ワークフロー
- [ ] 症状を正確に定義する（どのテーブル、カラム、行、時間範囲）
- [ ] 上流のリネージを辿り、データが最初に誤った段階を見つける
- [ ] 原因を分類する：コードバグ、入力データ不良、遅延データ、実行失敗？
- [ ] 疑わしい段階をそのソースと照合する（行数/合計値）
- [ ] 根本原因を修正し、影響を受けた時間帯の冪等なバックフィルを計画する
- [ ] 再発を防ぐチェックを追加する
- 症状を特定する。 「
fct_ordersの2026-01-15の収益が約30%低い」はデバッグ可能ですが、「数値がおかしい」はデバッグできません。テーブル、カラム、行、時間範囲を特定します。 - 上流のリネージを辿る。 誤った出力からモデル/タスクを逆向きにたどり、データが既に誤っている最初の段階を見つけます。すべての段階を読むのではなく、DAGを二分探索します。
- 原因を分類する： コード変更、入力データの不良/遅延、失敗/部分的な実行、または非冪等な重複。
- 疑わしい段階をその入力と照合する（行数、キー数、合計値）ことで、差分がどこで発生したかを確認します。
- 修正 + バックフィル 影響を受けた時間帯を冪等に実行します（
designing-backfills-and-replaysを参照）。 - 再発防止 対象を絞ったデータ品質チェックを追加します。
パターン
リネージ二分探索 — DAGの中間地点の段階をチェックします。そのデータが正しければバグは下流、誤っていればさらに上流へ。これを繰り返します。
ソース vs ターゲットの照合 を影響を受けた時間帯に対して行います：
-- 影響を受けた時間帯において、その段階と入力との間で件数・合計は一致するか？
SELECT 'source' AS layer, COUNT(*) n, SUM(amount) total
FROM staging.orders WHERE order_date = DATE '2026-01-15'
UNION ALL
SELECT 'target', COUNT(*), SUM(amount)
FROM marts.fct_orders WHERE order_date = DATE '2026-01-15';
件数が不一致 → 行のドロップ/フィルター、または失敗した部分ロード。件数が一致して合計値が不一致 → 変換・ロジックバグ。ターゲットの件数が多い → 重複（非冪等ロード）。
タイムラインチェック — インシデントの時間帯を、デプロイ、ソーススキーマ変更、実行履歴と関連付けます。ほとんどのインシデントは変更から始まります。
よくある落とし穴
- 下流で症状を修正する — バグがステージングにあるのにマートにパッチを当てると再発します。最初の不良段階を修正しましょう。
- 本番データに手動で一回限りの修正を加える — 監査できず再現性もありません。代わりにコードを修正し、冪等に再実行しましょう。
- DAG全体を線形に読む — 代わりにリネージの二分探索を行いましょう。
- 照合をスキップする — どこでデータが乖離したかを推測すると時間を浪費します。段階ごとに件数と合計値を測定しましょう。
- 修正後に予防的チェックを追加しない — 同じ種類のバグが気付かれずに再発します。