Restaurer et rejouer un pipeline
Bêta
Cette fonctionnalité est en version Bêta. Pour l'activer, définissez votre pipeline sur le canal de distribution Preview et configurez la configuration du pipeline pipelines.rewind.betaEnabled sur true. Consultez Requirements.
Une transformation erronée, un batch d'enregistrements sources mal formé ou un changement de schéma inattendu peuvent corrompre les tables d'un pipeline à partir d'un point dans le temps connu. La fonction de restauration ramène le pipeline à un point antérieur au problème afin que vous puissiez déployer un correctif et retraiter uniquement les données concernées.
Rewind restaure simultanément les versions de table, les décalages de source de streaming et l’état de l’opérateur, de sorte que la relecture ne saute pas d’enregistrements et n’écrit pas de doublons. Trois opérations retraitent les données et résolvent des problèmes différents :
- Le mot clé Rewind s’adresse à un pipeline récupérable qui a écrit des données incorrectes à partir d’un moment précis dans le temps, par exemple à la suite d’une transformation erronée, d’une entrée malformée ou d’un mauvais déploiement de code. Il restaure les données de table, les décalages de source et l’état de l’opérateur à un point antérieur au problème, puis il retraite uniquement les données concernées tout en conservant l’état de l’opérateur. Les données antérieures à ce point ne sont pas modifiées.
- 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 permet de récupérer un pipeline dont le point de contrôle est invalide ou corrompu, ou qui est bloqué par une modification de code incompatible avec le point de contrôle. Il Reset le point de contrôle et poursuit son exécution tout en préservant le contenu actuel de la table. Le retour arrière ne permet pas de résoudre ces cas, car il ne relâche pas les règles de compatibilité de Structured Streaming.
Prérequis
Exigence | Détail |
|---|---|
Canal | Le pipeline doit être sur le canal de distribution Prévisualisation . Consultez la page Configurer des pipelines. |
Configuration | Définissez la configuration du pipeline |
Mode pipeline | Pipelines déclenchés et continus. Le mode temps réel n’est pas pris en charge. |
Sources | Tables Delta, tables de streaming, Kafka, Amazon Kinesis et Auto Loader. |
Cibles | Tables de streaming et vues matérialisées. |
Flux | Flux en streaming et flux AUTO change data capture (CDC), y compris les cibles SCD de type 1 et SCD de type 2. Les requêtes stateful telles que les agrégations, les jointures et la déduplication sont prises en charge. |
Chaque flux du pipeline doit répondre à ces exigences. Lorsque pipelines.rewind.betaEnabled est true, un pipeline contenant un flux qui ne remplit pas les conditions échoue lors de ses mises à jour. Confirmez que chaque flux répond aux exigences ci-dessus avant de l’activer.
Un pipeline pour lequel pipelines.rewind.betaEnabled est défini sur true ne peut pas revenir au Canal de distribution Current tant que celui-ci n’est pas mis à jour vers un runtime prenant en charge le retour en arrière.
Fonctionnement du rembobinage et de la relecture
Le retour arrière et la relecture sont des étapes distinctes.
Rewind restitue chaque table à la version qu'elle possédait à un point de retour et réinitialise les points de contrôle du streaming qui permettent de suivre la progression de lecture de chaque flux. Vos transformations ne s'exécutent pas et aucune donnée source n'est retraitée.
Un rejeu s’effectue lors de la prochaine exécution du pipeline. Il effectue un nouveau traitement à partir du point de retour en arrière en utilisant la définition actuelle du pipeline, rattrape le retard jusqu'au moment présent, puis reprend le traitement incrémentiel normal. Le retour en arrière ne start pas le pipeline, vous devez donc le start vous-même lorsque vous êtes prêt.
Le pipeline génère des points de retour automatiquement, environ toutes les heures, et les conserve pendant 7 jours. Un pipeline que vous venez de créer ne dispose d’aucun point vers lequel revenir tant qu’il n’a pas généré son premier point.
La restauration d'un dataset restaure également tout ce qui se trouve en aval dans le même pipeline. La restauration couvre un seul pipeline. Il ne se coordonne pas avec d'autres pipelines ou avec des lecteurs externes des mêmes tables. Vous devez donc les gérer séparément.
Restaurer un pipeline à l’aide de l’interface utilisateur
L’interface utilisateur et Genie sont les principaux moyens d’utiliser le retour. L'interface utilisateur répertorie les points de rembobinage disponibles et indique les datasets affectés par chacun d'eux avant le commit.
- Sur votre page de pipeline, cliquez sur le bouton
situé à côté de Run pipeline , puis sur Rewind pipeline . - Sélectionnez un point de retour ou utilisez un raccourci tel que Rewind to yesterday ou Rewind to the latest point . Cliquez sur Suivant .
- Sélectionnez les tables à inclure. Utilisez la vue Graphe pour sélectionner des datasets dans le graphe du pipeline, ou la vue Liste pour les sélectionner à partir d'une table. Laissez Reset tous les points de contrôle sélectionné (default) pour restaurer les offsets source et l'état de l'opérateur avec les données de table, afin que le pipeline retraite à partir du point de retour arrière. Effacez-le pour restaurer uniquement les données de table, sans retraitement, par exemple lorsque vous souhaitez restaurer le contenu d'une table sans retraitement des données concernées. Ce paramètre doit être identique pour une table et ses amonts, et ne peut pas être effacé pour un flux qui lit une source externe telle que Kafka, Kinesis ou Auto Loader. Cliquez sur Suivant .
- Examinez le point de retour, le paramètre de point de contrôle et les datasets affectés, puis cliquez sur Restaurer .
start le pipeline pour rejouer les données.
Vous pouvez rembobiner à plusieurs reprises. Chaque retour en arrière remplace le précédent, de sorte que vous pouvez vous remettre d’une relecture échouée en effectuant un retour en arrière ailleurs.
Revenir en arrière dans un pipeline avec l’API, le CLI ou le SDK
En plus de l’interface utilisateur et de Genie, vous pouvez Trigger un retour en arrière par programmation avec le CLI Databricks, l’API REST ou le SDK Python. Utilisez le chemin de programmation pour l’automatisation, par exemple un job de réparation, un harnais de test ou un orchestrateur.
Un retour arrière est une mise à jour de pipeline unique dont le corps de la requête transporte un rewind_spec. Les champs dans rewind_spec définissent les mêmes choix que vous faites dans l’interface utilisateur : le point vers lequel revenir, les datasets à inclure et s’il faut reset les points de contrôle. La relecture est la prochaine mise à jour que vous envoyez sans rewind_spec, ce qui est l’équivalent API du démarrage du pipeline. Le retour arrière ne start pas le pipeline pour vous.
Vous pouvez cibler l'un des éléments suivants :
- Un point de retour en arrière (recommandé). Définissez
rewind_point_idsur l’un des points de retour en arrière générés par le pipeline. C’est le même choix que font l’interface utilisateur et Genie. Le point de retour enregistre déjà la version de la table et le point de contrôle à restaurer pour chaque dataset, de sorte que le retour restaure exactement cet état. Voir Trouver un point de retour. - Un Timestamp . Définissez
rewind_timestampsur un point arbitraire dans le temps lorsqu’aucun point de retour arrière généré ne correspond à l’état souhaité. Vous choisissez vous-même le Timestamp. Voir Revenir à un Timestamp.
Trouver un point de retour
Le pipeline enregistre chaque point de retour en arrière en tant qu’événement rewind_summary dans son journal d’événements. Le id de l’événement est le rewind_point_id. Chaque point de retour en arrière périodique enregistre la version actuelle de chaque table du pipeline. Une exécution à sec enregistre également un point de retour en arrière, pour l’état qu’elle a validé. Pour lister les points de retour en arrière des 7 derniers jours, exécutez une query comme la suivante :
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;
Les points de retour en arrière périodiques portent le message Periodic rewind summary capturing current table versions. Pour annuler des données incorrectes, choisissez le point de retour en arrière le plus récent dont timestamp précède l'écriture des données incorrectes.
Si l’ID ne correspond pas à un événement rewind_summary dans le journal des événements du pipeline, le rembobinage échoue avec INVALID_REWIND_SPECIFICATION.REWIND_POINT_NOT_FOUND.
Corps de requête de rembobinage
Pour revenir en arrière sur un pipeline, envoyez une mise à jour avec un corps rewind_spec comme celui-ci :
- 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
}
}
Retour en arrière avec le CLI
Le CLI Databricks transmet le corps de la requête via --json. Pour revenir en arrière sur un pipeline, exécutez la commande suivante :
- Rewind point
- Timestamp
La commande databricks pipelines start-update supprime rewind_point_id du corps de la requête. Envoyez plutôt la requête avec databricks api post, qui transmet le corps sans modification :
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>
Pour relire les données, start une mise à jour simple sans rewind_spec:
databricks pipelines start-update <pipeline-id> --profile <profile>
Pour interroger une mise à jour jusqu’à ce qu’elle atteigne un état terminal, exécutez ce qui suit :
databricks pipelines get-update <pipeline-id> <update-id> --profile <profile>
Retour en arrière avec l’API REST
Pour revenir en arrière sur un pipeline, envoyez une requête POST au Endpoint start une mise à jour avec le corps rewind_spec. Par exemple :
- 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
}
}'
Revenir en arrière avec le SDK Python
- Rewind point
- Timestamp
Le helper typé RewindSpec n’inclut pas rewind_point_id. Envoyez plutôt la requête avec le client REST authentifié du SDK. Cela fonctionne dans toutes les versions du SDK, y compris le databricks-sdk fourni avec Databricks Runtime et le compute serverless. Pour revenir en arrière sur un pipeline, exécutez ce qui suit :
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"])
L'assistant RewindSpec typé correspond directement au corps de la requête. Il nécessite databricks-sdk 0,40 et plus. Pour rembobiner un pipeline, exécutez ce qui suit :
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)
Le databricks-sdk fourni avec Databricks Runtime, y compris le compute serverless, peut être antérieur au RewindSpec typé. Dans un notebook, utilisez le client REST authentifié, disponible dans chaque version du SDK, afin de ne pas avoir à installer un SDK plus récent :
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,
},
})
Référence de spécification de retour en arrière
Le tableau suivant décrit les champs du corps de rewind_spec.
Champ | Description |
|---|---|
| La |
| Le point dans le temps auquel restaurer, au format UTC |
| Liste des datasets à rembobiner. Omettez la liste pour rembobiner tous les datasets du pipeline, chacun avec |
| Le nom complet du dataset à rembobiner, sous la forme |
| S'il faut aussi rembobiner chaque dataset en aval de celui-ci dans le pipeline. Spécifiez ce champ pour chaque dataset. Pour un pipeline linéaire, définissez-le sur |
| Indique s'il faut Reset les offsets de la source de streaming et l'état de l'opérateur afin que la relecture retraite à partir du point de retour. Il s’agit du paramètre Reset tous les points de contrôle de l’UI. La valeur default est |
| Indique si le retour en arrière doit être validé sans modifier aucune table. La valeur default est |
Lorsqu'un dataset racine lit une source externe comme Kafka, Kinesis ou Auto Loader, définissez reset_checkpoints sur true. L’interface utilisateur empêche d’effacer Reset tous les points de contrôle pour ces sources, mais l’API accepte une requête qui définit reset_checkpoints sur false. La requête est acceptée et le retour en arrière peut start, mais le pipeline échoue par la suite. Limitez reset_checkpoints: false aux datasets qu’un flux de streaming ne lit pas.
Rembobiner jusqu'à un timestamp
Utilisez rewind_timestamp lorsqu’aucun point de retour arrière généré ne correspond à l’état souhaité, par exemple pour revenir à un point entre deux points de retour arrière. Vous fournissez vous-même le Timestamp. Suivez deux règles :
- Choisissez un point strictement compris entre deux commits, pas un point qui tombe sur un commit. Un timestamp qui tombe sur un commit peut échouer à la relecture. Utilisez le point médian entre le dernier bon commit et le premier mauvais commit.
- Sur un pipeline qui n’a pas été rembobiné ou actualisé, analysez le flux de données de modification à partir de la version 1. La version 0 n’enregistre pas les données de modification. Si la version 1 est plus ancienne que la période de rétention du fichier de la table (7 jours default), l’analyse échoue. start donc à la place depuis la version la plus ancienne validée au cours de cette période.
La query ci-dessous, qui trouve les times de commit, lit le flux de données de modification (CDF) de la table de pipeline que vous voulez rembobiner, donc CDF doit être activé sur cette table. Le rembobinage lui-même ne nécessite pas CDF. Les pipelines LakeFlow Pipelines activent CDF sur leurs tables par default, donc la query fonctionne sans configuration supplémentaire. Si CDF a été désactivé sur la table, utilisez un point de rembobinage ou DESCRIBE HISTORY pour choisir un point à la place.
Faites correspondre le filtre _change_type à l'échec que vous examinez : pour les mauvaises insertions ou mises à jour, conservez 'insert' et 'update_postimage'; pour une suppression erronée, filtrez sur 'delete' à la place, car table_changes n'affiche les lignes supprimées que sous ce type de modification. Pour compute un timestamp de point médian à partir d'un prédicat qui sélectionne les mauvaises données, exécutez une query comme la suivante :
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;
Si le pipeline a déjà été rembobiné ou rafraîchi, start l'analyse à partir du dernier commit RESTORE ou refresh afin qu'il n'atteigne pas l'opération précédente.
Répéter un retour en arrière avec un test à sec
Pour valider un retour arrière sans modifier de table, définissez dry_run sur true. La mise à jour s’exécute via la validation jusqu’à un état COMPLETED terminal sans modifier les données. Utilisez une exécution à blanc pour confirmer que le pipeline accepte le retour arrière, puis envoyez à nouveau la requête avec dry_run défini sur false.
Un essai à blanc enregistre le retour en arrière qu'il a validé comme un événement rewind_summary. Pour appliquer exactement ce retour en arrière, par exemple après une simulation avec rewind_timestamp, envoyez le véritable retour en arrière avec id de l’événement en tant que rewind_point_id. Une simulation qui échoue ne bloque pas les mises à jour ultérieures.
Lorsque vous exécutez des cycles de retour en arrière et de relecture successifs en automatisation, exécutez un refresh complet entre eux. Empiler un second retour en arrière et une relecture sur un pipeline sans refresh complet entre les deux peut dupliquer les lignes retraitées dans les tables en streaming en aval.
eng-streamteam
Un échec de relecture laisse le pipeline rembobiné mais arrêté. Corrigez le code ou les données source et start le pipeline pour réessayer, ou rembobinez vers un point différent. Le pipeline ne revient pas en arrière de lui-même, et les erreurs apparaissent via les diagnostics standard du pipeline et l'event Logs.
La relecture ne réussit que si la définition actuelle du pipeline est compatible avec l’état restauré ; le retour en arrière ne modifie pas les règles de compatibilité de Structured Streaming. Pour connaître les modifications compatibles, consultez Types of changes in Structured Streaming queries. Les vues matérialisées suivent la sémantique de batch et tolèrent des modifications de schéma plus larges, mais échouent tout de même si une dépendance est incompatible.
Une restauration qui échoue en cours de route peut laisser le pipeline partiellement restauré. Vous avez deux options :
- Rembobinez à nouveau vers le même point ou vers un point différent, et le pipeline converge vers ce point.
- Pour forcer le pipeline à start une mise à jour normale malgré la restauration incomplète, définissez
pipelines.allowUpdateAfterIncompleteRewindsurtrueet redémarrez le pipeline.
Si un retour en arrière échoue ou si vous l'envoyez avec un point de retour en arrière non valide, le pipeline bloque toutes les mises à jour suivantes qui ne sont pas des retours en arrière, y compris un refresh complet, jusqu'à ce que vous émettiez à nouveau un retour en arrière valide. Lorsque vous Trigger des rembobinages par programmation, confirmez que rewind_point_id ou rewind_timestamp se réfère à un point valide avant d'envoyer la requête.
Jusqu'où vous pouvez remonter dans le temps
Les points de rembobinage sont conservés pendant 7 jours. Pendant cette période, un retour en arrière échoue si les données requises ont déjà été supprimées. Vérifiez ces éléments avant de recourir au rembobinage :
VACUUMou un brefdelta.deletedFileRetentionDurationsur vos tables. Consultez Travailler avec l'historique de la table.- Rétention de la source plus courte que la fenêtre sur laquelle vous souhaitez revenir en arrière, comme un sujet Kafka ou un Stream Kinesis qui ne conserve les données que pendant un jour.
Les pipelines dotés de plusieurs sources ou de longues chaînes de dépendance nécessitent une rétention plus importante, car chaque table et chaque point de contrôle doivent remonter jusqu'à un point cohérent.
Limitations
- La fonction de retour en arrière ne peut pas restaurer un pipeline à un point antérieur à un refresh complet.
- Les points de restauration sont conservés pendant 7 jours, et une restauration échoue si l'historique de la table ou les données source nécessaires pour atteindre ce point ont déjà été supprimés, par exemple par
VACUUMou en raison d'une courte période de rétention des sources. Consultez la rubrique Jusqu'où vous pouvez remonter dans le temps. - Le mode temps réel n’est pas pris en charge.
- Pulsar, Google Pub/Sub et les sources personnalisées créées avec les APIs de source de données Python ou DSv2 ne sont pas prises en charge en tant que sources.
- External sinks and custom sinks are not supported, including sinks defined with
create_sink(). See Use sinks in pipelines. - Les tables de streaming qui utilisent un filtre de ligne ou un masque de colonne ne peuvent pas être rembobinées. Voir Appliquer manuellement des filtres de lignes et des masques de colonnes.
- La restauration avec état nécessite le magasin d’états RocksDB, que les pipelines utilisent par default. Une restauration échoue pour un flux configuré avec un magasin d’états différent.
- Certaines tables en streaming AUTO CDC ont besoin d'un refresh avant de pouvoir être rembobinées. Le pipeline vous avertit lorsque vous demandez le rembobinage.
- Les vues matérialisées peuvent être entièrement recalculées plutôt que de faire l'objet d'un refresh incrémentiel après un retour en arrière. Voir Refresh incrémentiel pour les vues matérialisées.
- La fonction de retour couvre un seul pipeline et ne se coordonne pas avec les lecteurs externes ou d'autres pipelines lisant les mêmes tables.
- Le retour en arrière ne restaure pas le code du pipeline, la configuration du pipeline ou les métadonnées d'objets Unity Catalog telles que les tags et les attributions.