パイプラインの巻き戻しと再生
不適切な変換、不正な形式のソースレコードのバッチ、または予期しないスキーマ変更により、既知の時点以降、パイプラインのテーブルが誤った状態になる可能性があります。巻き戻しを行うと、問題が発生する前の時点にパイプラインが戻るため、修正をデプロイして影響を受けたデータのみを再処理することができます。
巻き戻し(Rewind)はテーブルのバージョン、ストリーミングソースのオフセット、およびオペレーターの状態を一緒に復元するため、リプレイによってレコードがスキップされたり重複が書き込まれたりすることがありません。3つの操作でデータを再処理し、それぞれ異なる問題を解決します:
- Rewind は、不適切な変換、不正な形式の入力、不良コードのデプロイなどにより、既知の時点から誤ったデータを書き込んだ リカバリ可能な パイプラインを対象としています。問題が発生する前の時点にテーブルのデータ、ソースオフセット、オペレーターの状態を復元し、オペレーターの状態を維持しながら、影響を受けたデータのみを再処理します。その時点より前のデータは変更されません。
- フル更新は、利用可能なすべてのソースデータからテーブルを再構築し、現在のコンテンツを破棄します。すべてを最初から再計算する場合や、コードの変更が既存の状態と互換性がない場合に使用します。
- Checkpoint reset recovers a パイプライン 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.
要件
Requirement | 詳細 |
|---|---|
チャンネル | パイプラインは Preview チャンネルを使用する必要があります。パイプラインの構成を参照してください。 |
構成 |
|
パイプラインモード | Trigger および連続パイプライン。リアルタイム モードはサポートされていません。 |
ソース | Delta テーブル、ストリーミングテーブル、Kafka、および Auto Loader。 |
ターゲット | ストリーミングテーブルとマテリアライズドビュー。 |
フロー | SCD Type 1およびSCD Type 2のターゲットを含む、ストリーミングフローおよびAUTOチェンジデータキャプチャ(CDC)フロー。集計、結合、重複排除などのステートフルクエリーがサポートされています。 |
パイプライン内のすべてのフローは、これらの要件を満たしている必要があります。pipelines.rewind.betaEnabled が true である間は、条件を満たさないフローを含むパイプラインの更新は失敗します。有効にする前に、すべてのフローが上記の要件を満たしていることを確認してください。
pipelines.rewind.betaEnabled が true に設定されているパイプラインは、現在のチャンネルがリワインドをサポートするランタイムに更新されるまで、現在のチャンネルに戻すことはできません。
復元とリプレイの仕組み
復元とリプレイは別々のステップです。
Rewind は、各テーブルを 復元ポイント 時点のバージョンに戻し、各フローの読み取り進捗を追跡するストリーミングチェックポイントをResetします。変換は実行されず、ソースデータは再処理されません。
リプレイ は、次回のパイプラインの実行時に発生します。現在のパイプライン定義を使用して復元ポイントから再処理を行い、現在に追いついてから、通常のインクリメンタル処理を再開します。復元ではパイプラインは起動しないため、準備ができたらご自身で起動してください。
パイプラインは約1時間に1回、自動的にリワインドポイントを生成し、7日間保持します。作成したばかりのパイプラインは、最初のチェックポイントが生成されるまで、リワインドできるポイントがありません。
データセットを巻き戻すと、同じパイプライン内のその下流にあるすべてのものも巻き戻されます。巻き戻しは1つのパイプラインを対象とします。他のパイプラインや、同じテーブルの外部リーダーとは連携しないため、それらは個別に管理してください。
UI を使用してパイプラインを復元する
UI と Genie は、rewind を使用するための主要な手段です。UI には利用可能な復元ポイントが一覧表示され、commit する前にそれぞれがどのデータセットに影響を与えるかが示されます。
- パイプラインのページで、
パイプラインをラン の横にある ボタンをクリックし、 パイプラインを巻き戻す をクリックします。
- 復元ポイントを選択するか、 「昨日の時点に復元」 や 「最新のポイントに復元」 などのショートカットを使用します。 「次へ」 をクリックします。
- Select which tables to include.パイプライン グラフでデータセットを選択するには グラフ ビューを使用し、テーブルから選択するには リスト ビューを使用します。ソースのオフセットとオペレーターの状態をテーブルデータとともに復元するには、 [すべてのチェックポイントをReset] を選択したまま (default) にし、パイプラインが復元ポイントから再処理するようにします。再処理を行わずにテーブルデータのみを復元するには、これをクリアします (たとえば、テーブルの内容を復元したいが、影響を受けるデータを再処理したくない場合など)。この設定は、テーブルとその上流で同じである必要があり、KafkaやAuto Loaderなどの外部ソースを読み取るフローに対してクリアすることはできません。 次へ をクリックします。
- 復元ポイント、チェックポイントの設定、および影響を受けるデータセットを確認し、 Rewind をクリックします。
データの再生を行うには、パイプラインを起動します。
何度も巻き戻しを実行できます。巻き戻すたびに前の状態が上書きされるため、別の場所に巻き戻すことで失敗したリプレイから復旧できます。
API、CLI、または SDK を使用してパイプラインを巻き戻す
UIおよびGenieに加えて、Databricks CLI、REST API、またはPython SDKを使用してプログラムで巻き戻しをTriggerできます。修復ジョブ、テストハーネス、オーケストレーターなどの自動化には、プログラムによるパスを使用します。
Rewind とは、リクエストの本文に rewind_spec が含まれている単一のパイプライン更新のことです。rewind_spec のフィールドでは、UI で選択する項目(復元先のポイント、含めるデータセット、チェックポイントを Reset するかどうか)と同じ項目を設定します。Replay とは、rewind_spec なしで送信する次の更新のことであり、パイプラインを起動する API と同等です。Rewind では、パイプラインは自動的に起動しません。
以下のいずれかをターゲットにできます。
- 巻き戻しポイント (推奨)。パイプラインによって生成された巻き戻しポイントのいずれかに
rewind_point_idを設定します。これは、UIとGenieが行う選択と同じです。巻き戻しポイントは各データセットを復元するためのテーブルバージョンとチェックポイントをすでに記録しているため、巻き戻しによってその状態が完全に復元されます。巻き戻しポイントを探す を参照してください。 - Timestamp 。生成された巻き戻しポイントが目的の状態と一致しない場合は、
rewind_timestampを任意の時点に設定します。Timestampは自分で選択します。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 本体を含む更新を送信します。
- Rewind point
- Timestamp
{
"cause": "USER_ACTION",
"rewind_spec": {
"rewind_point_id": "<rewind-point-id>",
"datasets": [
{
"identifier": "catalog.schema.table",
"cascade": true,
"reset_checkpoints": true
}
],
"dry_run": false
}
}
{
"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 を介してリクエストの本文を渡します。パイプラインを復元するには、以下を実行します:
- Rewind point
- Timestamp
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>
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による巻き戻し
パイプラインを巻き戻すには、rewind_spec本文を指定してアップデートの起動エンドポイントにPOSTリクエストを送信します。例えば:
- Rewind point
- 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_point_id": "<rewind-point-id>",
"datasets": [{"identifier": "catalog.schema.table", "cascade": true, "reset_checkpoints": true}],
"dry_run": false
}
}'
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での巻き戻し
- Rewind point
- Timestamp
型指定された RewindSpec ヘルパーには rewind_point_id は含まれていません。代わりに、SDK の認証済み REST クライアントを使用してリクエストを送信します。これは、Databricks Runtime および Serverless コンピュートにバンドルされている databricks-sdk を含む、すべての 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"])
型指定された 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)
Serverlessコンピュートを含む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本体のフィールドについて説明します。
フィールド | 説明 |
|---|---|
| 復元する |
| 復元する時点(UTC |
| 巻き戻すデータセットのリスト。リストを省略すると、パイプライン内のすべてのデータセットが巻き戻されます。各データセットの |
| 巻き戻すデータセットの完全修飾名( |
| パイプライン内のこのデータセットの下流にあるすべてのデータセットも復元するかどうか。各データセットについてこのフィールドを指定します。線形パイプラインの場合は、ルートデータセットでこれを |
| 再生が巻き戻しポイントから再処理されるように、ストリーミングソースのオフセットと演算子の状態をResetするかどうか。これは、UIの すべてのチェックポイントをResetする 設定です。default は |
| テーブルを変更せずに巻き戻しを検証するかどうか。default は |
ルートデータセットがKafkaやAuto Loaderなどの外部ソースを読み取る場合は、reset_checkpointsをtrueに設定したままにします。UIでは、これらのソースに対して「 Resetすべてのチェックポイント 」をオフにすることはできませんが、APIではreset_checkpointsをfalseに設定するリクエストを受け入れます。リクエストは受け入れられ、巻き戻しを起動できますが、その後パイプラインは失敗します。ストリーミングフローが読み取らないデータセットに reset_checkpoints: false を制限します。
Timestampの時点に復元
生成された巻き戻しポイントが目的の状態と一致しない場合(例えば、2つの巻き戻しポイントの間まで巻き戻したい場合など)に rewind_timestamp を使用します。ユーザー自身がTimestampを指定します。2つのルールに従います。
- 2つのcommitの間の厳密なポイントを選択します。commitに該当するポイントは選択しないでください。commitに該当するTimestampは、リプレイに失敗する可能性があります。最後に正常だったcommitと最初に問題があったcommitの中間点を使用します。
- 巻き戻しや更新が行われていないパイプラインでは、バージョン1からチェンジデータフィードをスキャンします。バージョン0には変更データが記録されません。バージョン1がテーブルのファイル保持期間(defaultでは7日間)より古い場合、スキャンは失敗します。そのため、その期間内にcommitされた最も古いバージョンから起動してください。
以下のクエリーは、commit時間を検索し、巻き戻すパイプラインテーブルのチェンジデータフィード (CDF) を読み取るため、そのテーブルでCDFが有効になっている必要があります。巻き戻し自体にチェンジデータフィードは必要ありません。Lakeflow パイプラインは、テーブルでチェンジデータフィードをdefaultで有効にするため、クエリーは追加設定なしで動作します。テーブルでチェンジデータフィードが無効になっている場合は、代わりに 巻き戻しポイント または DESCRIBE HISTORY を使用してポイントを選択してください。
調査対象の障害に合わせて_change_typeフィルターを一致させます。不正な挿入や更新の場合は'insert'と'update_postimage'を保持し、誤った削除の場合は代わりに'delete'でフィルターをかけます。これは、table_changesはその変更タイプでのみ削除された行を表示するためです。不良データを選択する述語から中間Timestampをコンピュートするには、次のクエリーをランします。
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 または更新 commit からスキャンを起動し、前の操作を超えないようにしてください。
ドライランによる巻き戻しのリハーサル
テーブルを変更せずに巻き戻しを検証するには、dry_run を true に設定します。更新は、データを変更せずに端末 COMPLETED 状態に検証をランします。パイプラインが巻き戻しを受け入れることを確認するためにドライランを使用し、次に dry_run を false に設定して再度要求を送信します。
ドライランは、検証した巻き戻しを rewind_summary イベントとして記録します。その巻き戻しを正確に適用する場合(例えば rewind_timestamp を使用してドライランを行った後など)、イベントの id を rewind_point_id として使用して実際の巻き戻しを送信します。失敗したドライランは、後の更新をブロックしません。
自動化で連続する巻き戻しと再生のサイクルを実行する場合は、その間でフル更新を実行してください。フル更新を挟まずにパイプラインで2回目の巻き戻しと再生を重ねると、ダウンストリームのストリーミングテーブルで再処理された行が重複する可能性があります。
復元後
リプレイが失敗すると、パイプラインは復元された状態で停止します。コードまたはソースデータを修正し、パイプラインを起動して再試行するか、別のポイントに復元します。パイプラインは自動的にはロールバックせず、エラーは標準的なパイプライン診断およびイベントLogsを通じて表面化します。
リプレイは、現在のパイプライン定義が復元された状態と互換性がある場合にのみ成功します。巻き戻しでは、Structured Streaming の互換性ルールは緩和されません。どの変更が互換性を持つかについては、Structured Streaming クエリーの変更の種類を参照してください。マテリアライズドビューはバッチセマンティクスに従い、より幅広いスキーマの変更を許容しますが、依存関係に互換性がない場合は引き続き失敗します。
途中で失敗したリワインドは、パイプラインが部分的にリワインドされた状態のままになる可能性があります。次の2つのオプションがあります。
- 同じポイントまたは別のポイントに再度巻き戻すと、パイプラインはそのポイントに収束します。
- 不完全な復元にもかかわらずパイプラインに通常の更新を強制的に起動させるには、
pipelines.allowUpdateAfterIncompleteRewindをtrueに設定してパイプラインを再起動します。
巻き戻しに失敗した場合、または無効な巻き戻しポイントで送信した場合、パイプラインは後続のすべての非巻き戻し更新(完全更新を含む)をブロックします。有効な巻き戻しを再発行するまで、ブロックは解除されません。プログラムで巻き戻しをTriggerする際は、リクエストを送信する前に rewind_point_id または rewind_timestamp が有効なポイントを参照していることを確認してください。
どこまで復元できるか
復元ポイントは 7 日間保持されます。eng-rewind-teameng-rewind-team
VACUUMまたは、テーブルに対して短いdelta.deletedFileRetentionDurationを実行します。テーブル履歴の操作を参照してください。- 1日間保持するKafkaトピックなど、さかのぼるために必要なウィンドウよりも短いソース保持期間。
複数のソースまたは長い依存関係チェーンを持つパイプラインでは、すべてのテーブルとチェックポイントが一貫した時点まで遡る必要があるため、より長い保持期間が必要です。
Limitations
- フル更新前の時点にはパイプラインを復元できません。
- 復元ポイントは7日間保持されます。復元先に到達するために必要なテーブル履歴またはソースデータが、
VACUUMやソースの短い保持期間などによってすでに削除されている場合、復元は失敗します。復元できる範囲については、こちらをご覧ください。 - リアルタイム モードはサポートされていません。
- Kinesis、Pulsar、Google Pub/Sub、および DSv2 または Python のデータソース API を使用して構築されたカスタムソースは、ソースとしてサポートされていません。
- External sinks and custom sinks are not supported, including sinks defined with
create_sink().「パイプラインでのシンクの使用」を参照してください。 - 行フィルターまたは列マスクを使用するストリーミングテーブルは巻き戻すことができません。行フィルターと列マスクの手動適用を参照してください。
- ステートフル巻き戻しには RocksDB 状態ストアが必要です。これは、パイプラインで default で使用されます。異なる状態ストアで構成されたフローの場合、巻き戻しは失敗します。
- 一部の AUTO CDC ストリーミングテーブルは、巻き戻す前に更新が必要です。パイプラインの巻き戻しをリクエストすると、通知が届きます。
- 巻き戻し後、マテリアライズドビューはインクリメンタル更新ではなく完全に再計算される場合があります。マテリアライズドビューの増分更新を参照してください。
- 巻き戻し(Rewind)は1つのパイプラインを対象としており、外部リーダーや同じテーブルを読み取る他のパイプラインとは連携しません。
- Rewind は、パイプラインのコード、パイプラインの構成、およびタグや権限などの Unity Catalog のオブジェクトメタデータを復元しません。