Remarque
L’accès à cette page requiert une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page requiert une autorisation. Vous pouvez essayer de modifier des répertoires.
Important
Cette fonctionnalité est en version bêta. Pour l’activer, mettez votre pipeline sur le canal Aperçu et définissez la configuration du pipeline pipelines.rewind.betaEnabled sur true. Consultez Spécifications.
Une mauvaise transformation, un lot déformé d’enregistrements sources ou un changement inattendu de schéma peuvent laisser les tables d’un pipeline incorrectes à partir d’un moment connu. Rewind ramène le pipeline à un point avant le problème afin que vous puissiez déployer une correction et ne retraiter que les données affectées.
Rewind restaure simultanément les versions de la table, les offsets des sources de streaming et l’état de l’opérateur, afin que la relecture n’ignore aucun enregistrement et n’entraîne pas d’écritures en double. Trois opérations retraitent les données, et elles résolvent différents problèmes :
- Rewind s’applique à un pipeline récupérable qui a écrit des données incorrectes depuis un point précis dans le temps, par exemple après une mauvaise transformation, des données d’entrée mal formées ou 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 avant le problème et ne retraite que les données affectées, en conservant l’état de l’opérateur. Les données antérieures à ce point restent intactes.
- Le rafraîchissement complet reconstruit un tableau à partir de toutes les données sources disponibles et en supprime le contenu actuel. Utilisez-le pour tout recalculer à partir de zéro, ou lorsqu’un changement de code n’est pas compatible avec l’état existant.
- La réinitialisation du point de contrôle récupère un pipeline dont le point de contrôle est invalide ou corrompu, ou qui est bloqué par un changement de code incompatible avec le point de contrôle. Il réinitialise le point de contrôle et continue d’avancer tout en préservant le contenu actuel de la table. Rewind ne peut pas récupérer ces cas, car il ne relâche pas les règles de compatibilité du Structured Streaming.
Exigences
| Requirement | Détails |
|---|---|
| Canal | Le pipeline doit être sur le canal Preview. Consultez Configurer des pipelines. |
| Configuration | Réglez la pipelines.rewind.betaEnabled configuration du pipeline sur true, puis exécutez le pipeline une fois. Chaque flux ne devient rembobinable qu’une fois sa mise à jour terminée avec l’option de voyage dans le temps activée. |
| Mode de pipeline | Pipelines déclenchés et en continu. Le mode temps réel n’est pas pris en charge. |
| Sources | Tables Delta, tables de streaming, Kafka et Auto Loader. |
| Cibles | Tables de streaming et vues matérialisées. |
| Flows | Flux en continu et flux de capture de données par changement automatique (CDC), incluant les cibles SCD Type 1 et SCD Type 2. Les requêtes avec état, telles que les agrégations, les jointures, et la déduplication, sont prises en charge. |
Chaque flux dans le pipeline doit répondre à ces exigences. Bien que pipelines.rewind.betaEnabled soit true, un pipeline contenant un flux qui ne remplit pas les critères voit ses mises à jour échouer. Confirmez que chaque flux répond aux exigences ci-dessus avant de l’activer.
Note
Un pipeline pour lequel pipelines.rewind.betaEnabled est défini sur true ne peut pas revenir au canal Current tant que celui-ci n’a pas été mis à jour vers une version du runtime qui prend en charge le rembobinage.
Comment fonctionnent le rembobinage et la relecture
Revenir et rejouer sont des étapes distinctes.
Rewind restaure chaque table à la version qu’elle détenait à un point de rembobinement et réinitialise les points de contrôle en streaming qui suivent la distance de lecture de chaque flux. Vos transformations ne s’exécutent pas, et aucune donnée source n’est retraitée.
Replay se produit la prochaine fois que le pipeline s’exécute. Il retraite les données à partir du point de rembobinage en utilisant la définition actuelle du pipeline, se remet à jour jusqu’au moment présent, puis reprend le traitement incrémental normal. Rewind ne démarre pas le pipeline, vous devez donc le démarrer vous-même lorsque vous êtes prêt(e).
Le pipeline génère automatiquement des points de rembobinage, environ une fois par heure, et les conserve pendant 7 jours. Un pipeline que vous venez de créer n’a aucun état antérieur auquel revenir avant d’avoir produit un premier résultat.
Le retour en arrière d’un jeu de données entraîne également celui de tous les éléments en aval dans le même pipeline. Rewind couvre un pipeline. Il ne se coordonne pas avec d’autres pipelines ni avec des lecteurs externes des mêmes tables, donc gérez-les séparément.
Relancer un pipeline via l’interface utilisateur
L’interface utilisateur et Genie sont les deux principaux moyens d’utiliser rewind. L’interface indique les points de retour en arrière disponibles et indique quels ensembles de données chacun affecte avant de valider le commit.
- Sur la page de votre pipeline, cliquez sur
à côté de Exécuter le pipeline, puis cliquez sur Rewind pipeline.
- Sélectionnez un point de rembobinage, ou utilisez un raccourci comme Rembobinage jusqu’à hier ou Rembobinage jusqu’au dernier point. Cliquez sur Suivant.
- Sélectionnez les tables à inclure. Utilisez la vue Graphe pour sélectionner les ensembles de données dans le graphe pipeline, ou la Vue Liste pour les sélectionner dans une table. Laissez l’option Réinitialiser tous les points de contrôle sélectionnée (option par défaut) pour restaurer les offsets de la source et l’état de l’opérateur ainsi que les données de la table, afin que le pipeline reprenne le traitement à partir du point de rembobinage. Effacez-le pour restaurer uniquement les données de la table, sans retraitement, par exemple lorsque vous souhaitez restaurer la sommaire d’une table mais que vous ne souhaitez pas retraiter les données affectées. Ce réglage doit être identique pour une table et ses sources amont, et il ne peut pas être désactivé pour un flux qui lit une source externe telle que Kafka ou Auto Loader. Cliquez sur Suivant.
- Examinez le point de rembobinage, le réglage du point de contrôle et les ensembles de données concernés, puis cliquez sur Rembobinage.
Lancez le pipeline pour relire les données.
Vous pouvez revenir en arrière plusieurs fois. Chaque rembobinage remplace le précédent, de sorte que vous pouvez récupérer après un échec de relecture en rembobinant à un autre endroit.
Réexécuter un pipeline en utilisant l’API, la CLI ou le SDK
En plus de l’interface utilisateur et de Genie, vous pouvez déclencher un rembobinement programmatiquement avec la ligne de commande de Databricks, l’API REST ou le SDK Python. Utilisez l’approche programmatique pour l’automatisation, comme une tâche de remédiation, un cadre de test ou un orchestrateur.
Un rembobinage est une mise à jour unique du pipeline dont le corps de requête porte un rewind_spec. Les champs du rewind_spec définissent les mêmes choix que vous faites dans l’interface : le point où revenir en arrière, les jeux de données à inclure et la question de réinitialiser les points de contrôle. Replay est la prochaine mise à jour que vous envoyez sans rewind_spec, ce qui est l’équivalent API du lancement du pipeline. Rewind ne lance pas le pipeline pour vous.
Vous pouvez cibler l’un des éléments suivants :
-
Un point de retour en arrière (recommandé). Réglez
rewind_point_idsur l’un des points de rembobinage générés par le pipeline. C’est le même choix que font l’interface utilisateur et Génie. Le point de retour en arrière enregistre déjà la version de la table et le point de contrôle à restaurer pour chaque jeu de données, donc la restauration restitue exactement cet état. Voir Rechercher un point de retour en arrière. -
Un horodatage. Réglez
rewind_timestampà un moment arbitraire où aucun point de retour généré ne correspond à l’état que vous souhaitez. Vous choisissez vous-même l’horodatage. Voir Revenir à un horodateur.
Trouvez un point de rembobinage
Le pipeline enregistre chaque point de rembobinage comme un rewind_summary événement dans son journal d’événements. Le id de l’événement est le rewind_point_id. Chaque point de rembobinage périodique enregistre la version actuelle de chaque table du pipeline. Un test à blanc enregistre également un point de retour en arrière, pour l’état qu’il a validé. Pour lister les points de retour en arrière des 7 derniers jours, lancez une requête 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 restauration périodiques ont le message Periodic rewind summary capturing current table versions. : Pour annuler les données incorrectes, choisissez le point de restauration le plus récent dont le timestamp est antérieur à l’écriture des données erronées.
Si l’ID ne correspond pas à un événement rewind_summary dans le journal d’événements du pipeline, le rembobinage échoue avec INVALID_REWIND_SPECIFICATION.REWIND_POINT_NOT_FOUND.
Corps de la requête de retour en arrière
Pour rembobiner un pipeline, envoyez une mise à jour avec un corps rewind_spec comme le suivant :
Point de rembobinage
{
"cause": "USER_ACTION",
"rewind_spec": {
"rewind_point_id": "<rewind-point-id>",
"datasets": [
{
"identifier": "catalog.schema.table",
"cascade": true,
"reset_checkpoints": true
}
],
"dry_run": false
}
}
Horodatage
{
"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 CLI
La CLI Databricks fait passer le corps de la requête par --json. Pour rembobiner un pipeline, exécutez ce qui suit :
Point de rembobinage
La commande databricks pipelines start-update supprime rewind_point_id du corps de la requête. Envoyez la demande avec databricks api post à la place, qui fait passer le corps sans modification :
databricks api post /api/2.0/pipelines/<pipeline-id>/updates --json @rewind.json --profile <profile>
Horodatage
databricks pipelines start-update <pipeline-id> --json @rewind.json --profile <profile>
Pour rejouer les données, lance une mise à jour simple sans rewind_spec:
databricks pipelines start-update <pipeline-id> --profile <profile>
Pour vérifier régulièrement l’état d’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>
Rembobiner avec l’API REST
Pour réinitialiser un pipeline, envoyez une requête POST au point de terminaison Démarrer une mise à jour avec le corps rewind_spec. Par exemple:
Point de rembobinage
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
}
}'
Horodatage
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
Point de rembobinage
L’assistant typé RewindSpec n’inclut pas rewind_point_id. Envoyez la requête avec le client REST authentifié du SDK à la place. Cela fonctionne dans toutes les versions du SDK, y compris celle databricks-sdk fournie avec Databricks Runtime et le calcul serverless. Pour rembobiner une chaîne de traitement, 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"])
Horodatage
Le programme d’assistance typé RewindSpec correspond directement au corps de la demande. Il faut 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 calcul serverless, pourrait être antérieur au RewindSpec typé. Dans un notebook, utilisez le client REST authentifié, disponible dans toutes les versions 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 la spécification de retour en arrière
Le tableau suivant décrit les champs dans le corps rewind_spec.
| Champ | Description |
|---|---|
rewind_point_id |
Le id d’un événement rewind_summary à restaurer. Voir Trouver un point de rembobinage. Définissez exactement l’un des deux : rewind_point_id ou rewind_timestamp. |
rewind_timestamp |
Le point dans le temps auquel restaurer, au format UTC yyyy-MM-dd HH:mm:ss. Voir Revenir à un horodateur. Définissez exactement un de rewind_point_id ou rewind_timestamp. |
datasets |
Liste des jeux de données à ramener à un état antérieur. Omettez la liste pour effectuer un retour en arrière sur tous les jeux de données du pipeline, avec les paramètres cascade et reset_checkpoints définis sur true. |
datasets[].identifier |
Nom entièrement qualifié du jeu de données sur lequel effectuer un retour en arrière, au format catalog.schema.table. |
datasets[].cascade |
S’il faut aussi rembobiner chaque jeu de données en aval de celui-ci dans le pipeline. Spécifiez ce champ pour chaque jeu de données. Pour un pipeline linéaire, définissez-le sur true dans le jeu de données racine pour effectuer un retour en arrière sur tout le pipeline. |
datasets[].reset_checkpoints |
S’il faut réinitialiser les décalages de la source en streaming et l’état de l’opérateur afin que la relecture soit retraitée à nouveau depuis le point de rembobinage. Il s’agit du paramètre Réinitialiser tous les points de contrôle de l’interface utilisateur. La valeur par défaut est true. Réglez-le sur false pour restaurer uniquement les données de table, sans retraitement. |
dry_run |
S’il faut valider le retour en arrière sans changer de table. La valeur par défaut est false. Voir Simuler un retour en arrière avec un test à blanc. |
Warning
Lorsqu’un jeu de données racine lit une source externe telle que Kafka ou Auto Loader, gardez reset_checkpoints défini sur true. L’interface empêche d’effacer Réinitialiser tous les points de contrôle pour ces sources, mais l’API accepte une requête qui définit reset_checkpoints sur false. La demande est acceptée et le rembobinage peut commencer, mais le pipeline de traitement échoue ensuite. Limitez reset_checkpoints: false aux jeux de données qu’un flux en streaming ne lit pas.
Rembobiner jusqu’à un horodatage
Utilisez rewind_timestamp lorsque aucun point de rembobinage généré ne correspond à l’état souhaité, par exemple pour rembobiner jusqu’à un point entre deux points de rembobinage. Vous fournissez vous-même l’horodatage. Suivez deux règles :
- Choisissez un point strictement entre deux commits, pas un point qui tombe sur un commit. Un horodatage qui tombe sur un commit peut faire échouer le rejeu. Utilise le point médian entre le dernier bon commit et le premier commit défectueux.
- Sur un pipeline qui n’a pas été réinitialisé ou actualisé, analysez le flux de données des modifications à partir de la version 1. La version 0 n’enregistre pas les données de modification. Si la version 1 est antérieure à la période de conservation des fichiers de la table (7 jours par défaut), le scan échoue, donc commencez par la version la plus ancienne validée dans cette période.
La requête ci-dessous, qui trouve les horodatages de commit, lit le flux de données de changement (CDF) de la table pipeline que vous souhaitez rembobiner, donc le CDF doit être activé sur cette table. Le rembobinage lui-même ne nécessite pas de CDF. Les pipelines Lakeflow activent par défaut le CDF sur leurs tables, donc la requête fonctionne sans configuration supplémentaire. Si CDF a été désactivé sur la table, utilisez un point de retour en arrière ou utilisez DESCRIBE HISTORY pour choisir un point à la place.
Associez le filtre _change_type à la défaillance que vous examinez : pour les insertions ou mises à jour incorrectes, 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 pour ce type de changement. Pour calculer un horodatage du point médian à partir d’un prédicat qui sélectionne les données défectueuses, lancez une requête comme suit :
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à fait l’objet d’un retour en arrière ou d’une actualisation, démarrez l’analyse à partir du dernier commit RESTORE ou d’actualisation afin de ne pas remonter au-delà de l’opération précédente.
Simuler un retour en arrière avec un test à blanc
Pour valider le retour en arrière sans changer de table, définissez dry_run sur true. La mise à jour passe par une phase de validation jusqu’à un état terminal COMPLETED sans modifier les données. Utilisez un test à blanc pour confirmer que le pipeline accepte le retour en arrière, puis envoyez à nouveau la requête avec dry_run défini sur false.
Un test à blanc enregistre le retour en arrière qu’il a considéré comme valide comme événement rewind_summary. Pour appliquer exactement ce retour en arrière, par exemple après un test à blanc avec rewind_timestamp, envoyez le véritable retour en arrière avec le id de l’événement comme rewind_point_id. Un essai blanc qui échoue ne bloque pas les mises à jour ultérieures.
Lorsque vous lancez des cycles successifs de retour en arrière et de relecture en automatisation, effectuez une actualisation entre eux. Empiler un second retour en arrière et un rejeu sur un pipeline sans rafraîchissement complet entre les deux peut dupliquer les lignes retraitées dans les tables de streaming en aval.
Après un retour en arrière
Une défaillance de relecture laisse le pipeline rembobiné mais arrêté. Corrigez le code ou les données sources et lancez le pipeline pour réessayer, ou remontez à un autre point. Le pipeline ne revient pas en arrière de lui-même, et des erreurs apparaissent via les diagnostics standards du pipeline et le journal des événements.
La relecture ne réussit que si la définition actuelle du pipeline est compatible avec l’état restauré ; le rewind ne relâche pas les règles de compatibilité du Structured Streaming. Pour les changements compatibles, voir Types de modifications dans les requêtes de streaming structuré. Les vues matérialisées suivent la sémantique par lots et tolèrent des changements de schéma plus larges, mais échouent tout de même si une dépendance est incompatible.
Un rembobinage qui échoue en partie peut laisser le pipeline partiellement rembobiné. Vous avez deux options :
- Remontez à nouveau jusqu’au même point ou à un autre, et le pipeline converge vers ce point.
- Pour forcer le pipeline à démarrer une mise à jour normale malgré le rembobinage incomplet, réglez
pipelines.allowUpdateAfterIncompleteRewindsurtrueet redémarrez le pipeline.
Note
Si un rembobinage échoue ou si vous l’envoyez avec un point de rembobinage invalide, le pipeline bloque toutes les mises à jour non-rembobinage suivantes, y compris un rafraîchissement complet, jusqu’à ce que vous soumettiez à nouveau un rembobinage valide. Lorsque vous déclenchez des retours en arrière par programmation, confirmez que rewind_point_id ou rewind_timestamp fait référence à un point valide avant d’envoyer la requête.
Jusqu’où pouvez-vous remonter en arrière
Les points de retour en arrière sont conservés pendant 7 jours. Pendant cette période, un retour en arrière échoue si les données dont il a besoin ont déjà été supprimées. Vérifiez les points suivants avant de compter sur le rembobinage :
-
VACUUMou undelta.deletedFileRetentionDurationbref dans vos tableaux. Voir Utiliser l’historique des tables. - Une durée de rétention de la source plus courte que la fenêtre sur laquelle vous souhaitez revenir en arrière, comme un topic Kafka qui conserve les données pendant un jour.
Les pipelines comportant plusieurs sources ou de longues chaînes de dépendances nécessitent une durée de rétention plus longue, car chaque table et chaque point de contrôle doit pouvoir remonter jusqu’à un point cohérent.
Limitations
- Le retour en arrière ne peut pas restaurer un pipeline à un état antérieur à une actualisation complète.
- Les points de rembobinage sont conservés pendant 7 jours, et l’opération de rembobinage échoue si l’historique de la table ou les données source nécessaires pour revenir à ce point ont déjà été supprimés, par exemple par
VACUUMou en raison d’une courte durée de rétention des données source. Voyez jusqu’où vous pouvez remonter en arrière. - Le mode temps réel n’est pas pris en charge.
- Kinesis, Pulsar, Google Pub/Sub et des sources personnalisées construites avec les API de source de données DSv2 ou Python ne sont pas prises en charge comme sources.
- Les puits externes et les puits personnalisés ne sont pas pris en charge, y compris les puits définis avec
create_sink(). Consultez Utiliser des récepteurs dans des pipelines. - Les tables de streaming utilisant un filtre de ligne ou un masque de colonne ne peuvent pas être rembobinées. Consultez Appliquer manuellement des filtres de lignes et des masques de colonne.
- Le retour arrière avec état nécessite le stockage d’état RocksDB, que les pipelines utilisent par défaut. Un retour en arrière échoue pour un flux configuré avec un autre store d’état.
- Certaines tables de streaming AUTO CDC ont besoin d’une mise à jour avant de pouvoir être rembobinées. Le pipeline vous avertit lorsque vous demandez un retour en arrière.
- Les vues matérialisées peuvent être entièrement recalculées plutôt que d’être actualisées de façon incrémentielle après un retour en arrière. Consultez Actualisation incrémentielle pour les vues matérialisées.
- Rewind couvre un pipeline et n’assure aucune coordination avec des lecteurs externes ni avec d’autres pipelines qui lisent les mêmes tables.
- Rewind ne restaure pas le code du pipeline, la configuration du pipeline, ni les métadonnées des objets du catalogue Unity telles que les tags et les concessions.