回退和重播管道

Important

此功能在 Beta 版中。 要启用它,请将管道设置为 预览 通道,并将管道配置设置为 pipelines.rewind.betaEnabledtrue。 请参阅 要求。

错误的转换、源记录批次的错误或意外的模式变更,都可能导致管道表从已知时间点开始出现错误。 倒带会将流水线返回问题发生前的某个点,这样你可以部署修复并只重新处理受影响的数据。

Rewind 会同时恢复表版本、流式数据源偏移量和算子状态,从而确保回放时不会跳过记录或写入重复记录。 三种操作对数据进行重处理,解决不同的问题:

  • 倒带适用于可恢复的流水线,这类流水线自某个已知时间点起写入了错误数据,例如在错误转换、格式错误的输入或错误的代码部署之后。 它会将表数据、源偏移量和操作符状态恢复到问题发生前的某个点,并仅重新处理受影响的数据,保持操作符状态。 该时间点之前的数据未被修改。
  • 完全刷新使用所有可用的源数据重新构建表,并丢弃其当前内容。 用它从头重新计算,或者当代码变更与现有状态不兼容时。
  • 检查点重置 用于恢复检查点无效或已损坏,或者因与检查点不兼容的代码变更而被阻塞的流水线。 它会重置检查点,并在保留表的当前内容的同时继续向前推进。 Rewind无法恢复这些情况,因为它没有放宽结构化流兼容性规则。

要求

Requirement 详情
通道 管道必须位于 预览 通道。 请参阅 “配置管道”。
Configuration 将流水线配置true设置为 pipelines.rewind.betaEnabled ,然后运行一次流水线。 每个流程只有在完成一次启用了时间旅行的更新后,才会变为可回退。
管道模式 触发式和连续管道。 不支持实时模式。
Sources Delta 表、流式表、Kafka 和 Auto Loader。
目标 流式表格和实体视图。
Flows 流式数据流和 AUTO 变更数据捕获(CDC)流,包括 SCD 类型 1 和 SCD 类型 2 目标表。 支持有状态查询,例如聚合、联接和去重。

管道中的每一次流量都必须满足这些要求。 当 pipelines.rewind.betaEnabled 为 true 时,包含不符合条件的流的管道更新将会失败。 在启用之前,请确认每个流程都满足上述要求。

注释

将 pipelines.rewind.betaEnabled 设置为 true 的流水线无法移回 Current 通道,除非 Current 通道更新到支持回退的运行时。

倒带和回放的工作原理

倒带和回放是两个独立的步骤。

倒带会将每个表恢复到其在倒带点时的版本,并重置用于记录每个流已读取到何处的流式检查点。 你的转换不会运行,也不会重新处理源数据。

重放会在流水线下次运行时发生。 它会按照当前的流水线定义从回退点开始重新处理,追赶至当前状态,然后恢复正常的增量处理。 Rewind 不会启动该流程,因此请在准备就绪后自行启动。

该管道会自动生成回退点,频率约为每小时一次,并将其保留 7 天。 你刚创建的管道在产生第一个结果之前,还没有可回退到的内容。

回退某个数据集也会将同一流水线中其下游的所有内容一并回退。 回退支持一个管道。 它不与其他管道或同一表的外部读取器协调,因此应分别管理这些数据。

使用 UI 回退管道

使用 Rewind 的两种主要方式是 UI 和 Genie。 界面会列出可用的回退点,并在你提交前显示每个回退点会影响哪些数据集。

  1. 在管道页面上,点击 按钮(位于 下倒V字形图标。运行管道 旁边),然后点击 回退管道。
  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 设置为流水线生成的倒带点之一。 这也是界面和 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 而失败。

回退请求正文

要回退管道,请发送一个更新,其 rewind_spec 主体如下:

回退点

{
  "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 Runtime 和无服务器计算随附的 databricks-sdk。 要回退管道,请运行以下命令:

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 Runtime 提供的 databricks-sdk(包括无服务器计算)可能早于类型化的 RewindSpec。 在笔记本环境中,使用经过身份验证的 REST 客户端,该客户端在每个 SDK 版本中都可用,这样您就不必安装更新版本的 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 正文中的字段。

领域 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. 请参见通过试运行演练回退流程。

Warning

当根数据集读取外部来源(如 Kafka 或 Auto Loader)时,保持 reset_checkpoints 为 true。 UI 阻止针对这些源清除重置所有检查点,但 API 接受将 reset_checkpoints 设置为 false 的请求。 接受请求后,可以启动回退,但随后管道会失败。 将 reset_checkpoints: false 限制为流式流不会读取的数据集。

回退到时间戳处

当没有生成的回退点与目标状态匹配时,请使用 rewind_timestamp,例如可回退到两个回退点之间的某一点。 时间戳你自己提供。 请遵循两条规则:

  • 选择一个严格介于两个提交之间的点,而不是落在一个提交上的点。 时间戳恰好对应某个提交时,可能导致重放失败。 使用上一次良好提交和第一次坏提交之间的中点。
  • 对于尚未回退或刷新的管道,请扫描版本 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,然后重启流水线。

注释

如果倒带失败或发送了无效的倒带点,流水线会阻止所有后续非倒带更新,包括完全刷新,直到你重新发起一次有效的倒带操作。 当你通过程序触发倒带时,在发送请求前,确认 rewind_point_id 或 rewind_timestamp 引用一个有效点。

你最多可以回退多远

回退点将保留 7 天。 在该时间窗口内,如果回退所需的数据已被移除,则回退将失败。 在依赖 Rewind 之前,请先检查以下几点:

  • VACUUM,或对您的表缩短 delta.deletedFileRetentionDuration。 请参阅处理表历史记录。
  • 源数据保留时长短于你想要回溯的时间窗口,例如某个只保留一天数据的 Kafka 主题。

包含多个数据源或较长依赖链的管道需要更长的保留期,因为每个表和检查点都必须能够回溯到同一个一致的时间点。

局限性

  • Rewind 无法将流水线恢复到执行完全刷新之前的时间点。
  • 回退点会保留 7 天;如果回退到该时间点所需的表历史记录或源数据已被移除,则回退将失败,例如由于 VACUUM 或源数据保留期过短。 看看 你能倒回多久。
  • 不支持实时模式。
  • Kinesis、Pulsar、Google Pub/Sub 以及使用 DSv2 或 Python 数据源 API 构建的自定义源码不被支持作为源码。
  • 不支持外部汇和自定义汇,包括定义为 create_sink()的汇。 请参阅 在管道中使用接收器。
  • 使用行筛选或列掩码的流式表无法回溯。 请参阅 手动应用行筛选器和列掩码。
  • 有状态回退需要 RocksDB 状态存储,而管道默认使用该存储。 对于配置了不同状态存储的流,回退会失败。
  • 某些 AUTO CDC 流式表需要先刷新,然后才能回退。 当你请求回退时,管道会通知你。
  • 实体化视图在回退后可能会执行完全重新计算,而不是进行增量刷新。 请参阅具体化视图的增量刷新。
  • Rewind 仅适用于一个管道,不会与外部读取程序或其他读取同一表的管道进行协调。
  • Rewind 不会恢复流水线代码、流水线配置或 Unity 目录对象元数据,如标签和授权。

其他资源