Rewind and replay a pipeline

Important

This feature is in Beta. To enable it, set your pipeline to the Preview channel and set the pipelines.rewind.betaEnabled pipeline configuration to true. See Requirements.

A bad transformation, a malformed batch of source records, or an unexpected schema change can leave a pipeline's tables wrong from a known point in time forward. Rewind returns the pipeline to a point before the problem so that you can deploy a fix and reprocess only the affected data.

Rewind restores table versions, streaming source offsets, and operator state together, so replay does not skip records or write duplicates. Three operations reprocess data, and they solve different problems:

  • Rewind is for a recoverable pipeline that wrote incorrect data from a known point in time, such as after a bad transformation, malformed input, or a bad code deploy. It restores table data, source offsets, and operator state to a point before the problem and reprocesses only the affected data, keeping operator state. Data before that point is untouched.
  • Full refresh rebuilds a table from all available source data and discards its current contents. Use it to recompute everything from scratch, or when a code change is not compatible with the existing state.
  • Checkpoint reset recovers a pipeline whose checkpoint is invalid or corrupted, or that is blocked by a checkpoint-incompatible code change. It resets the checkpoint and continues forward while preserving the table's current contents. Rewind cannot recover these cases, because it does not relax Structured Streaming compatibility rules.

Requirements

Requirement Detail
Channel The pipeline must be on the Preview channel. See Configure pipelines.
Configuration Set the pipelines.rewind.betaEnabled pipeline configuration to true, then run the pipeline once. Each flow becomes rewindable only after it completes an update with time travel enabled.
Pipeline mode Triggered and continuous pipelines. Real-time mode is not supported.
Sources Delta tables, streaming tables, Kafka, and Auto Loader.
Targets Streaming tables and materialized views.
Flows Streaming flows and AUTO change data capture (CDC) flows, including SCD Type 1 and SCD Type 2 targets. Stateful queries such as aggregations, joins, and deduplication are supported.

Every flow in the pipeline must meet these requirements. While pipelines.rewind.betaEnabled is true, a pipeline containing a flow that does not qualify fails its updates. Confirm that every flow meets the requirements above before you enable it.

Note

A pipeline that has pipelines.rewind.betaEnabled set to true cannot move back to the Current channel until the Current channel is updated to a runtime that supports rewind.

How rewind and replay work

Rewind and replay are separate steps.

Rewind restores each table to the version it held at a rewind point and resets the streaming checkpoints that track how far each flow has read. Your transformations do not run, and no source data is reprocessed.

Replay happens the next time the pipeline runs. It reprocesses from the rewind point using the current pipeline definition, catches up to the present, then resumes normal incremental processing. Rewind does not start the pipeline, so start it yourself when you are ready.

The pipeline generates rewind points automatically, about once an hour, and keeps them for 7 days. A pipeline you just created has nothing to rewind to until it produces its first one.

Rewinding a dataset also rewinds everything downstream of it in the same pipeline. Rewind covers one pipeline. It does not coordinate with other pipelines or with external readers of the same tables, so manage those separately.

Rewind a pipeline using the UI

The UI and Genie are the primary ways to use rewind. The UI lists the available rewind points and shows which datasets each one affects before you commit.

  1. On your pipeline page, click the Chevron down icon. button next to Run pipeline, then click Rewind pipeline.
  2. Select a rewind point, or use a shortcut such as Rewind to yesterday or Rewind to the latest point. Click Next.
  3. Select which tables to include. Use the Graph view to select datasets in the pipeline graph, or the List view to select them from a table. Leave Reset all checkpoints selected (the default) to restore source offsets and operator state along with the table data, so the pipeline reprocesses from the rewind point. Clear it to restore the table data only, without reprocessing, for example when you want a table's contents restored but do not want to reprocess the affected data. This setting must be the same for a table and its upstreams, and it cannot be cleared for a flow that reads an external source such as Kafka or Auto Loader. Click Next.
  4. Review the rewind point, the checkpoint setting, and the affected datasets, then click Rewind.

Start the pipeline to replay the data.

You can rewind repeatedly. Each rewind replaces the last, so you can recover from a failed replay by rewinding somewhere else.

Rewind a pipeline using the API, CLI, or SDK

In addition to the UI and Genie, you can trigger a rewind programmatically with the Databricks CLI, the REST API, or the Python SDK. Use the programmatic path for automation, such as a remediation job, a test harness, or an orchestrator.

A rewind is a single pipeline update whose request body carries a rewind_spec. The fields in the rewind_spec set the same choices you make in the UI: the point to rewind to, the datasets to include, and whether to reset checkpoints. Replay is the next update you send with no rewind_spec, which is the API equivalent of starting the pipeline. Rewind does not start the pipeline for you.

You can target either of the following:

  • A rewind point (recommended). Set rewind_point_id to one of the rewind points that the pipeline generated. This is the same choice that the UI and Genie make. The rewind point already records the table version and checkpoint to restore for each dataset, so the rewind restores exactly that state. See Find a rewind point.
  • A timestamp. Set rewind_timestamp to an arbitrary point in time when no generated rewind point matches the state you want. You choose the timestamp yourself. See Rewind to a timestamp.

Find a rewind point

The pipeline records each rewind point as a rewind_summary event in its event log. The event's id is the rewind_point_id. Each periodic rewind point records the current version of every table in the pipeline. A dry run also records a rewind point, for the state it validated. To list the rewind points from the last 7 days, run a query like the following:

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 points have the message Periodic rewind summary capturing current table versions. To undo bad data, pick the most recent rewind point whose timestamp is before the bad data was written.

If the ID does not match a rewind_summary event in the pipeline's event log, the rewind fails with INVALID_REWIND_SPECIFICATION.REWIND_POINT_NOT_FOUND.

Rewind request body

To rewind a pipeline, send an update with a rewind_spec body like the following:

Rewind point

{
  "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
  }
}

Rewind with the CLI

The Databricks CLI passes the request body through --json. To rewind a pipeline, run the following:

Rewind point

The databricks pipelines start-update command drops rewind_point_id from the request body. Send the request with databricks api post instead, which passes the body through unchanged:

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>

To replay the data, start a plain update with no rewind_spec:

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

To poll an update until it reaches a terminal state, run the following:

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

Rewind with the REST API

To rewind a pipeline, send a POST request to the Start an update endpoint with the rewind_spec body. For example:

Rewind point

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
    }
  }'

Rewind with the Python SDK

Rewind point

The typed RewindSpec helper does not include rewind_point_id. Send the request with the SDK's authenticated REST client instead. This works in every SDK version, including the databricks-sdk bundled with Databricks Runtime and serverless compute. To rewind a pipeline, run the following:

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

The typed RewindSpec helper maps directly to the request body. It requires databricks-sdk 0.40 and above. To rewind a pipeline, run the following:

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)

The databricks-sdk bundled with Databricks Runtime, including serverless compute, might predate the typed RewindSpec. In a notebook, use the authenticated REST client, which is available in every SDK version, so that you do not have to install a newer 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 reference

The following table describes the fields in the rewind_spec body.

Field Description
rewind_point_id The id of a rewind_summary event to restore to. See Find a rewind point. Set exactly one of rewind_point_id or rewind_timestamp.
rewind_timestamp The point in time to restore to, in UTC yyyy-MM-dd HH:mm:ss format. See Rewind to a timestamp. Set exactly one of rewind_point_id or rewind_timestamp.
datasets The list of datasets to rewind. Omit the list to rewind all datasets in the pipeline, each with cascade and reset_checkpoints set to true.
datasets[].identifier The fully qualified name of the dataset to rewind, in catalog.schema.table form.
datasets[].cascade Whether to also rewind every dataset downstream of this one in the pipeline. Specify this field for each dataset. For a linear pipeline, set it to true on the root dataset to rewind the whole pipeline.
datasets[].reset_checkpoints Whether to reset streaming source offsets and operator state so that replay reprocesses from the rewind point. This is the UI's Reset all checkpoints setting. Defaults to true. Set it to false to restore table data only, without reprocessing.
dry_run Whether to validate the rewind without changing any table. Defaults to false. See Rehearse a rewind with a dry run.

Warning

When a root dataset reads an external source such as Kafka or Auto Loader, keep reset_checkpoints set to true. The UI prevents clearing Reset all checkpoints for these sources, but the API accepts a request that sets reset_checkpoints to false. The request is accepted and the rewind can start, but the pipeline fails afterward. Limit reset_checkpoints: false to datasets that a streaming flow does not read.

Rewind to a timestamp

Use rewind_timestamp when no generated rewind point matches the state you want, for example to rewind to a point between two rewind points. You supply the timestamp yourself. Follow two rules:

  • Choose a point strictly between two commits, not one that falls on a commit. A timestamp that lands on a commit can fail replay. Use the midpoint between the last good commit and the first bad commit.
  • On a pipeline that has not been rewound or refreshed, scan the change data feed from version 1. Version 0 does not record change data. If version 1 is older than the table's file retention period (7 days by default), the scan fails, so start from the oldest version committed within that period instead.

The query below, which finds the commit times, reads the change data feed (CDF) of the pipeline table you want to rewind, so CDF must be enabled on that table. The rewind itself doesn't require CDF. Lakeflow pipelines enable CDF on their tables by default, so the query works without extra setup. If CDF has been disabled on the table, use a rewind point or DESCRIBE HISTORY to pick a point instead.

Match the _change_type filter to the failure you are investigating: for bad inserts or updates, keep 'insert' and 'update_postimage'; for an erroneous delete, filter on 'delete' instead, because table_changes surfaces deleted rows only under that change type. To compute a midpoint timestamp from a predicate that selects the bad data, run a query like the following:

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;

If the pipeline has already been rewound or refreshed, start the scan from the latest RESTORE or refresh commit so that it does not reach past the earlier operation.

Rehearse a rewind with a dry run

To validate a rewind without changing any table, set dry_run to true. The update runs through validation to a terminal COMPLETED state without modifying data. Use a dry run to confirm that the pipeline accepts the rewind, then send the request again with dry_run set to false.

A dry run records the rewind it validated as a rewind_summary event. To apply exactly that rewind, for example after a dry run with rewind_timestamp, send the real rewind with the event's id as rewind_point_id. A dry run that fails does not block later updates.

When you run successive rewind-and-replay cycles in automation, run a full refresh between them. Stacking a second rewind and replay on a pipeline without a full refresh in between can duplicate the reprocessed rows in downstream streaming tables.

After a rewind

A replay failure leaves the pipeline rewound but stopped. Fix the code or the source data and start the pipeline to retry, or rewind to a different point. The pipeline does not roll back on its own, and errors surface through standard pipeline diagnostics and the event log.

Replay only succeeds if the current pipeline definition is compatible with the restored state; rewind does not relax Structured Streaming compatibility rules. For which changes are compatible, see Types of changes in Structured Streaming queries. Materialized views follow batch semantics and tolerate broader schema changes, but still fail if a dependency is incompatible.

A rewind that fails partway can leave the pipeline partially rewound. You have two options:

  1. Rewind again to the same point or a different one, and the pipeline converges on that point.
  2. To force the pipeline to start a normal update despite the incomplete rewind, set pipelines.allowUpdateAfterIncompleteRewind to true and restart the pipeline.

Note

If a rewind fails or you send it with an invalid rewind point, the pipeline blocks every subsequent non-rewind update, including a full refresh, until you re-issue a valid rewind. When you trigger rewinds programmatically, confirm that rewind_point_id or rewind_timestamp refers to a valid point before you send the request.

How far back you can rewind

Rewind points are kept for 7 days. Within that window, a rewind fails if the data it needs has already been removed. Check for these before you rely on rewind:

  • VACUUM or a short delta.deletedFileRetentionDuration on your tables. See Work with table history.
  • Source retention shorter than the window you want to rewind across, such as a Kafka topic that keeps one day.

Pipelines with several sources or long dependency chains need more retention, because every table and checkpoint has to reach back to a consistent point.

Limitations

  • Rewind cannot restore a pipeline to a point before a full refresh.
  • Rewind points are kept for 7 days, and a rewind fails if the table history or source data needed to reach the point has already been removed, for example by VACUUM or short source retention. See How far back you can rewind.
  • Real-time mode is not supported.
  • Kinesis, Pulsar, Google Pub/Sub, and custom sources built with the DSv2 or Python data source APIs are not supported as sources.
  • External sinks and custom sinks are not supported, including sinks defined with create_sink(). See Use sinks in pipelines.
  • Streaming tables that use a row filter or a column mask cannot be rewound. See Manually apply row filters and column masks.
  • Stateful rewind requires the RocksDB state store, which pipelines use by default. A rewind fails for a flow configured with a different state store.
  • Some AUTO CDC streaming tables need a refresh before they can be rewound. The pipeline notifies you when you request the rewind.
  • Materialized views might fully recompute rather than incrementally refresh after a rewind. See Incremental refresh for materialized views.
  • Rewind covers one pipeline and does not coordinate with external readers or other pipelines reading the same tables.
  • Rewind does not restore pipeline code, pipeline configuration, or Unity Catalog object metadata such as tags and grants.

Additional resources

  • Sidst opdateret den