回溯並重播管線

Important

這項功能位於 測試版 (Beta) 中。 要啟用它,請將管線設為 預覽 通道,並將 pipelines.rewind.betaEnabled 管線設定設為 true。 請參閱 需求。

錯誤的轉換、來源記錄批次錯誤,或意外的結構變更,都可能讓管線的資料表從已知時間點開始出現錯誤。 Rewind 會將管線回傳到問題發生前的某個點,這樣你就可以部署修正並只重新處理受影響的資料。

Rewind 會同時還原資料表版本、串流來源偏移量和運算子狀態,因此重播時不會跳過記錄或寫入重複記錄。 三個操作會重新處理資料,並解決不同的問題:

  • 倒轉 適用於可復原的管線:這類管線從某個已知時間點開始寫入錯誤資料,例如在錯誤的轉換、格式錯誤的輸入,或不良的程式碼部署之後。 它會將資料表資料、來源偏移量和運算子狀態恢復到問題發生前的某點,並只處理受影響的資料,並保留運算子狀態。 該時間點之前的資料未經變動。
  • 完整刷新 會從所有可用原始資料重建表格,並丟棄其目前的內容。 用它從頭重新計算所有東西,或當程式碼變更與現有狀態不相容時。
  • 檢查點重置 可恢復檢查點無效或損壞,或因檢查點不相容程式碼變更而阻塞的管線。 它會重置檢查點並繼續前進,同時保留資料表目前的內容。 Rewind 無法恢復這些案例,因為它並未放寬結構化串流相容性規則。

要求

Requirement Detail
Channel 管線必須位於 預覽 通道。 請參見 「配置管線」。
組態 將 pipelines.rewind.betaEnabled 管線設定為 true,然後執行管線一次。 每個流程只有在完成一次啟用時間旅行的更新後,才會變得可回溯。
管線模式 觸發式與連續式管線。 不支援即時模式。
Sources Delta 表格、串流表格、Kafka 和 Auto Loader。
目標 串流資料表與實體化視圖。
Flows 串流流程和 AUTO 變更資料擷取(CDC)流程,包括 SCD 第 1 類和 SCD 第 2 類目標。 支援有狀態查詢,例如聚合、聯結與去重。

管線中的每條流程都必須符合這些要求。 當 pipelines.rewind.betaEnabled 是 true時,包含不符合資格的流程的管線會失敗更新。 啟用前,請確認每個流程都符合上述要求。

Note

將 pipelines.rewind.betaEnabled 設定為 true 的管線,在「目前」通道更新為支援回溯的執行階段之前,無法移回「目前」通道。

倒帶與重播的運作方式

倒帶和重播是分開的步驟。

回溯 會將每個資料表還原至 回溯點 時的版本,並重設用來追蹤各流程讀取到哪裡的串流檢查點。 你的轉換不會執行,且沒有原始資料被重新處理。

下一次管線運行時會重播。 它會根據目前的管線定義,從回溯點重新處理,追趕至目前進度,然後恢復正常的增量處理。 Rewind 不會啟動該管線,因此請在準備就緒後自行啟動。

管線會自動產生回復點,約每小時一次,並將其保留 7 天。 你剛建立的管線在產生第一個可回溯點之前,沒有可回溯的內容。

將資料集回溯,也會將同一管線中位於其下游的所有項目一併回溯。 Rewind 適用於一個管道。 它不會與其他管線或相同資料表的外部讀取器協調,因此請分別管理這些資料表。

使用 UI 將管線回復到先前狀態

UI 和 Genie 是使用 rewind 的主要方式。 介面會列出可用的倒帶點,並在你提交前顯示各倒帶點會影響哪些資料集。

  1. 在管線頁面上,按一下 按鈕(位於 下倒叉形圖示。執行管線 旁邊),然後按一下 回溯管線。
  2. 選擇倒帶點,或使用捷徑如「 倒帶到昨天 」或「 倒帶到最新時間點」。 按一下「下一步」。
  3. 選擇要包含哪些表格。 使用 圖 視圖來選擇管線圖中的資料集,或使用 清單 視圖從表格中選取資料集。 維持重置所有檢查點為已選取狀態(預設值),即可還原來源偏移量、運算子狀態以及資料表資料,讓管線從回溯點開始重新處理。 清除它只用於還原資料表資料,不重新處理,例如當你想還原資料表內容但不想重新處理受影響的資料時。 此設定在資料表及其上游項目中必須相同,且對於讀取 Kafka 或 Auto Loader 等外部來源的流程,不得清除此設定。 按一下「下一步」。
  4. 檢視倒帶點、檢查點設定及受影響的資料集,然後點擊 倒帶。

啟動管線以重新播放資料。

你可以重複倒帶。 每次倒帶都會取代上一次,所以你還能從失敗的重玩中倒帶到別處來恢復。

使用 API、CLI 或 SDK 回退流程

除了 UI 和 Genie,你還可以用 Databricks CLI、REST API 或 Python SDK 以程式方式觸發回溯。 使用以程式方式進行自動化,例如修復作業、測試框架或協調器。

倒帶是單一的管線更新,其請求體包含一個 rewind_spec。 rewind_spec 中的欄位會設定和你在 UI 中做的一樣的選擇:要倒帶到的時間點、要包含的資料集,以及是否要重設檢查點。 Replay 是你在未帶有 rewind_spec 的情況下所傳送的下一個更新,這在 API 上相當於啟動管線。 倒帶不會幫你啟動流程。

你可以選擇以下任一目標:

  • 一個回溯點(建議)。 將 rewind_point_id 設為管線產生的其中一個倒帶點。 這也是 UI 和 Genie 做出的同樣選擇。 倒帶點已經記錄了每個資料集要還原的表格版本和檢查點,所以倒帶會完全還原該狀態。 參見 「尋找回溯點」。
  • 一個時間戳記。 將 rewind_timestamp 設為任意時間點,當沒有任何產生的倒帶點與你想要的狀態相符時。 時間戳記由你自己決定。 請參見 「倒帶至時間戳」。

尋找倒轉點

管線會將每個倒帶點作為 rewind_summary 事件記錄在其 事件日誌 中。 事件的 id 是 rewind_point_id。 每個週期倒帶點會記錄管線中每個資料表的當前版本。 模擬執行也會記錄一個還原點,針對它所驗證的狀態。 要列出過去7天的倒帶點,請執行如下查詢:

SELECT id AS rewind_point_id, timestamp, message
FROM event_log('<pipeline-id>')
WHERE event_type = 'rewind_summary'
  AND details:rewind_summary.dry_run = true
  AND timestamp > current_timestamp() - INTERVAL 7 DAYS
ORDER BY timestamp DESC;

定期倒帶點具有 Periodic rewind summary capturing current table versions. 訊息:要撤銷錯誤資料,請選擇其 timestamp 位於錯誤資料寫入之前的最近倒帶點。

若 ID 與管線事件日誌中的事件rewind_summary 不符,倒帶會因 INVALID_REWIND_SPECIFICATION.REWIND_POINT_NOT_FOUND 而失敗。

倒帶請求本文

要倒帶管線,請傳送主體如下的更新:

倒帶點

{
  "cause": "USER_ACTION",
  "rewind_spec": {
    "rewind_point_id": "<rewind-point-id>",
    "datasets": [
      {
        "identifier": "catalog.schema.table",
        "cascade": true,
        "reset_checkpoints": true
      }
    ],
    "dry_run": false
  }
}

Timestamp

{
  "cause": "USER_ACTION",
  "rewind_spec": {
    "rewind_timestamp": "2026-09-29 08:36:55",
    "datasets": [
      {
        "identifier": "catalog.schema.table",
        "cascade": true,
        "reset_checkpoints": true
      }
    ],
    "dry_run": false
  }
}

用 CLI 回復

Databricks CLI 會透過 --json 傳遞請求本文。 要倒帶管道,請執行以下操作:

倒帶點

databricks pipelines start-update 指令會從請求本文中移除 rewind_point_id。 改為使用 databricks api post 傳送請求,這樣會將本文原封不動地傳遞過去:

databricks api post /api/2.0/pipelines/<pipeline-id>/updates --json @rewind.json --profile <profile>

Timestamp

databricks pipelines start-update <pipeline-id> --json @rewind.json --profile <profile>

要重播資料,請開始一個不含 rewind_spec 的純更新:

databricks pipelines start-update <pipeline-id> --profile <profile>

要輪詢更新直到達到終端狀態,執行以下操作:

databricks pipelines get-update <pipeline-id> <update-id> --profile <profile>

使用 REST API 倒帶

要倒帶管線,請向 POST 端點發送 請求,並使用 rewind_spec 要求本文。 例如:

倒帶點

curl -sS -X POST \
  "https://<workspace-host>/api/2.0/pipelines/<pipeline-id>/updates" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cause": "USER_ACTION",
    "rewind_spec": {
      "rewind_point_id": "<rewind-point-id>",
      "datasets": [{"identifier": "catalog.schema.table", "cascade": true, "reset_checkpoints": true}],
      "dry_run": false
    }
  }'

Timestamp

curl -sS -X POST \
  "https://<workspace-host>/api/2.0/pipelines/<pipeline-id>/updates" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cause": "USER_ACTION",
    "rewind_spec": {
      "rewind_timestamp": "2026-09-29 08:36:55",
      "datasets": [{"identifier": "catalog.schema.table", "cascade": true, "reset_checkpoints": true}],
      "dry_run": false
    }
  }'

用 Python SDK 回溯

倒帶點

該型別 RewindSpec 輔助器不包含 rewind_point_id。 改用 SDK 認證的 REST 用戶端發送請求。 這在所有 SDK 版本中都適用,包括 databricks-sdk 隨 Databricks Runtime 和無伺服器運算套件附帶的版本。 若要倒帶管道,請執行下列操作:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()  # In a notebook, authenticates as the notebook identity.
resp = w.api_client.do("POST", f"/api/2.0/pipelines/{pipeline_id}/updates", body={
    "cause": "USER_ACTION",
    "rewind_spec": {
        "rewind_point_id": rewind_point_id,
        "datasets": [{"identifier": root_table, "cascade": True, "reset_checkpoints": True}],
        "dry_run": False,
    },
})
print(resp["update_id"])

Timestamp

具型別的 RewindSpec 輔助工具直接對應到請求主體。 它需要 databricks-sdk 0.40 以上。 要倒帶管道,請執行以下操作:

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.pipelines import StartUpdateCause, RewindSpec, RewindDatasetSpec

w = WorkspaceClient(profile="<profile>")
resp = w.pipelines.start_update(
    "<pipeline-id>",
    cause=StartUpdateCause.USER_ACTION,
    rewind_spec=RewindSpec(
        rewind_timestamp="2026-09-29 08:36:55",
        datasets=[RewindDatasetSpec(
            identifier="catalog.schema.table",
            cascade=True,
            reset_checkpoints=True,
        )],
        dry_run=False,
    ),
)
print(resp.update_id)

Databricks 執行時隨附的 databricks-sdk(包括無伺服器運算)可能早於型別化的 RewindSpec。 在筆記本中,使用所有 SDK 版本中都有的認證 REST 用戶端,這樣你就不必安裝較新的 SDK:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()  # Authenticates as the notebook identity.
w.api_client.do("POST", f"/api/2.0/pipelines/{pipeline_id}/updates", body={
    "cause": "USER_ACTION",
    "rewind_spec": {
        "rewind_timestamp": rewind_timestamp,
        "datasets": [{"identifier": root_table, "cascade": True, "reset_checkpoints": True}],
        "dry_run": False,
    },
})

倒帶規格說明

下表描述了 rewind_spec 主體中的欄位。

Field Description
rewind_point_id 要還原至的 rewind_summary 事件的 id。 參見 「尋找倒帶點」。 請僅設定 rewind_point_id 或 rewind_timestamp 其中一個。
rewind_timestamp 還原時間點,以 UTC yyyy-MM-dd HH:mm:ss 格式。 請參見 倒帶至時間戳記。 請恰好設定 rewind_point_id 或 rewind_timestamp 其中一個。
datasets 要還原的資料集清單。 省略清單即可將管線中的所有資料集倒帶,其中每個資料集的 cascade 和 reset_checkpoints 均設為 true。
datasets[].identifier 要回溯之資料集的完整限定名稱,格式為 catalog.schema.table。
datasets[].cascade 是否也要倒帶管線中此資料集下游的每個資料集。 為每個資料集指定此欄位。 對於線性管線,在根資料集上將其設為 true,這樣可以倒帶整個管線。
datasets[].reset_checkpoints 是否要重設串流來源偏移量和運算子狀態,以便讓重播從回退點重新處理。 這是介面的 「重置所有檢查點」 設定。 預設為 true。 設定為 false 只還原資料表資料,不重新處理。
dry_run 是否要驗證倒帶而不更換任何資料表。 預設為 false。 請參考以 dry run 演練復原。

Warning

當根資料集讀取外部來源(如 Kafka 或 Auto Loader)時,請將 reset_checkpoints 設為 true。 介面會阻止清空這些來源的 重置所有檢查點,但 API 會接受將 reset_checkpoints 設為 false 的請求。 請求被接受後,回溯可以開始,但之後管線會失敗。 限制 reset_checkpoints: false 於串流流程未讀取的資料集。

倒帶到時間戳記

當沒有任何產生的倒帶點與你想要的狀態相符時,請使用 rewind_timestamp,例如要倒帶到兩個倒帶點之間的某一點。 時間戳記你自己提供。 請遵守兩條規則:

  • 選擇一個嚴格位於兩個提交之間,而不是落在一個提交上的點。 時間戳記對應到某個 commit 時,可能無法重播。 利用上一次良好提交版本和第一個壞提交版本之間的中間點。
  • 對於尚未倒帶或重新整理的管線,掃描自版本 1 起的變更資料饋送。 版本 0 不會記錄變更資料。 如果版本 1 比資料表的檔案保留期(預設為 7 天)還要舊,掃描會失敗,因此請從該期間內提交的最舊版本開始。

以下查詢會找出提交時間,並讀取你想倒帶的管線資料表的變更資料饋(CDF),因此該表必須啟用 CDF。 倒帶本身不需要 CDF。 Lakeflow 管線預設在資料表啟用 CDF,因此查詢無需額外設定即可運作。 如果資料表上的 CDF 已被停用,請改用 回溯點 或 DESCRIBE HISTORY 來選擇一個點。

將篩選器與你正在調查的失敗相匹配 _change_type:對於錯誤的插入或更新,保留 'insert' 和 'update_postimage';對於錯誤刪除,則改為依 'delete' 篩選,因為 table_changes 只會在該變更類型下顯示已刪除的資料列。 要從選擇壞資料的謂詞計算中點時間戳,請執行如下查詢:

WITH onset AS ( -- The first commit that introduced the bad data.
  SELECT min(_commit_version) AS first_bad_version,
         min(_commit_timestamp) AS first_bad_ts
  FROM table_changes('catalog.schema.table', 1) -- Start from version 1.
  WHERE _change_type IN ('insert', 'update_postimage') -- Use ('delete') instead to find an erroneous delete.
    AND (event_date >= '2026-09-29') -- Example predicate. Replace the condition in parentheses with one that selects the bad rows.
),
bounds AS (
  SELECT first_bad_ts,
         (SELECT max(h.timestamp)
          FROM (DESCRIBE HISTORY catalog.schema.table) h
          WHERE h.version < onset.first_bad_version) AS last_good_ts
  FROM onset
)
SELECT date_format(
         from_unixtime((unix_timestamp(last_good_ts) + unix_timestamp(first_bad_ts)) / 2),
         'yyyy-MM-dd HH:mm:ss') AS rewind_timestamp
FROM bounds;

如果管線已經被倒帶或重新整理,請從最新 RESTORE 或重新整理提交開始掃描,避免超過先前的操作。

用模擬執行來排練還原

若要驗證回退而不更改任何表格,請設 dry_run 為 true。 更新過程會進行驗證至最終 COMPLETED 狀態,且不修改資料。 用試跑確認管線是否接受倒帶,然後將 dry_run 設為 false 後,再次發送請求。

模擬演練會將經驗證的倒帶記錄為 rewind_summary 事件。 若要精確套用該回溯,例如在使用 rewind_timestamp 進行試跑後,請將事件的 id 作為 rewind_point_id 傳送實際的回溯。 失敗的試運行不會阻止後續更新。

當你在自動化中連續執行倒帶和重播循環時,在它們之間做一次完整的重新整理。 在沒有完全刷新的情況下,在管線上堆疊第二次倒帶和重播,可能會使下游串流資料表中的已重新處理資料列重複出現。

倒帶之後

重新播放失敗會使管線回退,但處於停止狀態。 修正程式碼或原始資料,然後啟動管線重試或倒帶到另一個點。 管線不會自行回滾,錯誤會透過標準管線診斷和事件日誌浮現。

只有當目前的管線定義與已還原的狀態相容時,重放才會成功;倒帶不會放寬 Structured Streaming 的相容性規則。 關於哪些變更相容,請參見 結構化串流查詢中的變更類型。 實體化檢視遵循批次語意並容忍更廣泛的結構變更,但若相依不相容仍會失敗。

回捲若在進行到一半時失敗,可能會使管線處於部分回捲的狀態。 你有兩個選擇:

  1. 再倒帶到同一點或另一個點,管線就會收斂到那個點。
  2. 若要在回復未完成的情況下仍強制管線開始正常更新,請將 pipelines.allowUpdateAfterIncompleteRewind 設為 true,然後重新啟動管線。

Note

如果倒帶失敗或你發送的倒帶點無效,管線會阻擋所有後續非倒帶更新,包括完整刷新,直到你重新發出有效的倒帶。 當你用程式方式觸發倒帶時,請先確認 rewind_point_id 或 rewind_timestamp 是否指向有效的點,再發送請求。

可回溯到多久之前

還原點會保留 7 天。 在該時間範圍內,如果回溯所需的資料已遭移除,回溯就會失敗。 在依賴 rewind 功能之前,請先確認以下幾點:

  • VACUUM 或是在你的桌上放一個短的 delta.deletedFileRetentionDuration。 請參見 使用表格歷史記錄。
  • 來源資料保留期限短於你想回溯的時間範圍,例如僅保留一天的 Kafka 主題。

具有多個來源或較長相依性鏈的管線需要更長的保留期,因為每個資料表和檢查點都必須回溯到一致的時間點。

Limitations

  • Rewind 無法將管線還原到完整重新整理前的某個時間點。
  • 倒帶點會保留 7 天;如果為了回到該時間點所需的資料表歷史記錄或來源資料已遭移除,則倒帶作業會失敗,例如因為 VACUUM 或來源資料保留期間過短。 請參閱你可以回溯到多久之前。
  • 不支援即時模式。
  • Kinesis、Pulsar、Google Pub/Sub 以及使用 DSv2 或 Python 資料來源 API 建置的自訂原始碼不被支援作為原始碼。
  • 外部合成器與自訂合成器不被支援,包括定義為 create_sink()的 。 請參見 :在管線中使用水槽。
  • 使用列過濾器或欄遮罩的串流資料表無法倒帶。 請參閱 手動應用列篩選器和欄位遮罩。
  • 狀態式回溯需要使用 RocksDB 狀態存放區,而管線預設會使用此存放區。 對於設定為使用不同狀態存放區的流程,回溯會失敗。
  • 有些 AUTO CDC 串流資料表需要先重新整理,之後才能回溯。 當你要求回捲時,管線會通知你。
  • 實體化檢視在回溯後,可能會進行完整重新計算,而非增量更新。 如需具體化檢視 ,請參閱累加式重新整理。
  • Rewind 只涵蓋一條管線,不會與外部讀取器或其他讀取相同資料表的管線協調。
  • Rewind 不會還原管線程式碼、管線設定或 Unity Catalog 物件元資料(如標籤和授權)。

其他資源