偵錯資料管線 是做什麼的？
使用時機
- 管線任務失敗，或輸出資料錯誤/遺失/重複。
- 儀表板過時，或某個指標與來源不一致。
- 利害關係人回報差異，必須找出原因。
- 請勿用於已由
debugging-dbt-runs/debugging-airflow-pipelines處理的工具特定執行錯誤（應先使用那些技能，若屬資料正確性事故再使用本技能）。
工作流程
- [ ] 精確定義症狀（哪個資料表、欄位、資料列、時間區間）
- [ ] 向上追溯血緣，找出資料首次出現錯誤的階段
- [ ] 隔離原因：是程式碼錯誤、錯誤輸入、資料延遲，還是執行失敗？
- [ ] 比對可疑階段與其來源（計數/總和）
- [ ] 修復根本原因，然後規劃受影響區間的冪等回填
- [ ] 增加檢查，確保問題不會悄悄重現
- 釘選症狀。「2026-01-15 的營收在
fct_orders中低了約 30%」是可偵錯的；「數字看起來不對」則不是。取得資料表、欄位、資料列與時間區間。 - 向上追溯血緣。 從錯誤輸出向後逐步檢查模型/任務，找到第一個資料已經錯誤的階段。對有向無環圖進行二元搜尋，而不是逐一檢查每個階段。
- 分類原因： 程式碼變更、錯誤/延遲的來源資料、失敗/部分執行，或非冪等的重複。
- 比對可疑階段與其輸入（資料列數、鍵值計數、總和），以確認差異出現在何處。
- 修復 + 回填受影響區間，確保冪等性（參見
designing-backfills-and-replays）。 - 防止重複發生，加入有針對性的資料品質檢查。
常見模式
血緣二元搜尋 — 檢查有向無環圖中一半位置的階段：如果其資料正確，則錯誤在下游；如果錯誤，則繼續向上搜尋。重複此過程。
比對來源與目標（針對受影響的區間）：
-- 在錯誤區間內，該階段與其輸入的計數/總和是否一致？
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';
計數差異 → 資料列被篩選/丟棄，或部分載入失敗。計數相同但總和不同 → 轉換/邏輯錯誤。目標計數較高 → 重複（非冪等載入）。
時間線檢查 — 將事故時間區間與部署、來源結構變更及執行歷程關聯起來；大多數事故都始於某次變更。
常見陷阱
- 在下游修補症狀 — 當錯誤在暫存層時，只修復市集層會導致問題重現；應修復第一個錯誤的階段。
- 對生產資料進行一次性手動修復 — 無法稽核且不可重複；應修復程式碼並以冪等方式重新執行。
- 線性閱讀整個有向無環圖 — 應改用二元搜尋血緣的方式。
- 跳過比對步驟 — 憑猜測判斷資料在哪裡分歧只會浪費時間；應測量每個階段的計數與總和。
- 修復後未加入預防性檢查 — 同類錯誤會悄悄再次出現。