Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Les pipelines Lakeflow simplifient la capture des données modifiées (CDC) avec les API AUTO CDC et AUTO CDC FROM SNAPSHOT. Ces API automatisent la complexité du calcul des dimensions lentes changeantes (SCD) Type 1 et Type 2 à partir d’un flux CDC ou d’instantanés de base de données, et l’API AUTO CDC calcule également l’historique bitemporel à partir d’un flux CDC. Pour en savoir plus sur SCD Type 1, SCD Type 2 et bitemporal, voir Capture des données de modification et instantanés.
Note
Les AUTO CDC API remplacent les APPLY CHANGES API et ont la même syntaxe. Les APPLY CHANGES API sont toujours disponibles, mais Databricks recommande d’utiliser les AUTO CDC API à leur place.
L’API que vous utilisez dépend de la source de vos données modifiées :
-
AUTO CDC: Utilisez ceci lorsque la base de données source a un flux CDC activé.AUTO CDCtraite les changements à partir d’un flux de données de changement (CDF). Il est pris en charge dans les interfaces SQL et Python du pipeline. -
AUTO CDC FROM SNAPSHOT: Utilisez ceci lorsque le CDC n’est pas activé sur la base de données source et que seuls les instantanés sont disponibles. Cette API compare les instantanés pour déterminer les modifications, puis les traite. Il est pris en charge dans les interfaces SQL et Python du pipeline.
Pour les cibles de type SCD 1, on peut aussi combiner un AUTO CDC FROM SNAPSHOT flow avec un ou plusieurs AUTO CDC flows. Utilisez ce schéma lorsqu’une source fournit des instantanés autoritaires périodiques et un flux CDC à faible latence entre les instantanés.
Les API prennent en charge les types de stockage suivants pour les tables cibles :
- SCD Type 1 : Mettre à jour les enregistrements directement. L’historique n’est pas conservé pour les enregistrements mis à jour. Pris en charge par les deux API.
- SCD Type 2 : Conserver un historique des enregistrements, soit sur toutes les mises à jour, soit sur les mises à jour d’un ensemble spécifié de colonnes. Pris en charge par les deux API.
-
Bitemporal : conserver l’historique des enregistrements sur deux lignes temporelles : le temps métier, quand un changement a pris effet, et le temps système, au moment où le système l’a enregistré. Pris en charge par
AUTO CDCuniquement. Voir Bitemporal AUTO CDC.
AUTO CDC prend également en charge les mises à jour partielles, où un enregistrement de changement ne met à jour qu’un sous-ensemble de colonnes. Consultez Appliquer des mises à jour partielles.
Les AUTO CDC API ne sont pas prises en charge par les pipelines déclaratifs Apache Spark.
Pour la syntaxe et d'autres références, consultez AUTO CDC INTO (pipelines), create_auto_cdc_flow et create_auto_cdc_from_snapshot_flow.
Note
Utilisez ces API pour mettre à jour les tables dans vos pipelines en fonction des changements dans les données sources. Pour savoir comment enregistrer et interroger des informations de modification au niveau des lignes pour les tables Delta, consultez Utiliser le flux de données modifiées sur Azure Databricks.
Spécifications
Pour utiliser les API CDC, votre pipeline doit être configuré pour utiliser les pipelines Lakeflow serverless ou l’une desPro Lakeflow pipelines Advanced.
Comment fonctionne AUTO CDC
Pour effectuer le traitement CDC avec AUTO CDC, créez une table de diffusion en continu, puis utilisez l’instruction AUTO CDC ... INTO dans SQL ou la fonction create_auto_cdc_flow() en Python pour spécifier la source, les clés et le séquencement du flux de modification. Pour obtenir une explication sur le fonctionnement du séquencement et de la logique SCD, consultez Modifier la capture et les instantanés de données. Consultez les exemples AUTO CDC.
Pour une hydratation initiale à partir d'une source avec un flux de modification, utilisez AUTO CDC avec un flux once, puis continuez à traiter le flux de modification. Consultez Répliquer une table RDBMS externe à l’aide de l’AUTO CDC.
Pour plus d’informations sur la syntaxe, consultez AUTO CDC INTO (pipelines) ou create_auto_cdc_flow.
Comment fonctionne AUTO CDC FROM SNAPSHOT
AUTO CDC FROM SNAPSHOT détermine les changements dans les données sources en comparant des instantanés dans l’ordre. Vous pouvez lire des instantanés à partir d’une table Delta, de fichiers de stockage cloud ou de JDBC directement. Il est pris en charge dans les interfaces SQL et Python du pipeline.
Pour effectuer un traitement CDC avec AUTO CDC FROM SNAPSHOT, créez une table de streaming puis définissez le flux :
- En SQL, utilisez la forme
AUTO CDC ... FROM SNAPSHOTde l’instructionCREATE FLOWou la clause intégréeFLOW AUTO CDCdeCREATE STREAMING TABLE. La source est une clauseFROM SNAPSHOT (snapshot_query)requise et une clauseWITH VERSION (version_query)facultative qui sélectionne la prochaine version de l'instantané à traiter. Voir CREATE FLOW (pipelines). - En Python, utilisez la fonction
create_auto_cdc_from_snapshot_flow()pour spécifier l’instantané, les clés et d’autres arguments. Voir create_auto_cdc_from_snapshot_flow.
Pour plus d’informations sur les deux modèles d’ingestion et sur le moment où les utiliser, consultez les modèles de traitement par instantané. Consultez les exemples AUTO CDC FROM SNAPSHOT.
Combinez AUTO CDC FROM SNAPSHOT et AUTO CDC
La version de l’instantané et la colonne de séquencement CDC appartiennent au même domaine d’ordonnancement. Un événement CDC plus récent que le dernier instantané prime sur le snapshot. Un instantané plus récent prime sur les anciens événements CDC et considère les clés absentes du instantané comme supprimées dans la version du snapshot. Les événements CDC plus récents peuvent préserver ou restaurer ces clés.
Une cible unifiée doit répondre aux exigences suivantes :
- La cible utilise le SCD Type 1.
- La cible a exactement un
AUTO CDC FROM SNAPSHOTflux et un ou plusieursAUTO CDCflux. - Chaque
AUTO CDCflux porte un nom unique. - Tous les flux utilisent le même nombre de clés, dans le même ordre. Les noms des clés du flux d’instantané sont comparés sans tenir compte de la casse aux noms des clés
AUTO CDC. Les flux multiplesAUTO CDCdoivent utiliser des noms de clés et une casse identiques. - La version de snapshot et chaque colonne de séquençage CDC ont exactement le même type de données.
- Le
AUTO CDC FROM SNAPSHOTflow ne définit pas les attentes. - Les
AUTO CDCflux n’utilisent pasIGNORE NULL UPDATESni ses variantes de liste de colonnes. - Le pipeline utilise le mode déclenché.
- Si vous ajoutez un
AUTO CDCflux à une cible existanteAUTO CDC FROM SNAPSHOT, la cible ne doit pas contenir de colonnes utilisateur dont les noms entrent en conflit avec les colonnes système réservéesAUTO CDC.
Les flux AUTO CDC et AUTO CDC FROM SNAPSHOT peuvent utiliser l’interface de pipeline Python ou SQL. Vous pouvez combiner des flux SQL et Python dans une même cible.
Utilisez once=True dans Python ou ONCE dans SQL dans le flux AUTO CDC FROM SNAPSHOT pour remplir un instantané une seule fois pendant que les flux AUTO CDC continuent de traiter les nouveaux événements lors des mises à jour suivantes. Une actualisation complète de la cible réexécute le flux d’instantané à exécution unique. Pour un exemple complet, voir Ajouter un remplissage à une table AUTO CDC SCD Type 1.
Ce modèle ne prend pas en compte les cibles SCD Type 2 ni bitemporelles.
Utiliser plusieurs colonnes pour le séquencement
Pour séquencer sur plusieurs colonnes (par exemple, un horodatage et un ID afin de départager les égalités), utilisez une STRUCT pour les combiner. L’API commande d’abord par le premier champ, et en cas d’égalité, considère le deuxième champ, et ainsi de suite.
SQL
SEQUENCE BY STRUCT(timestamp_col, id_col)
Python
sequence_by = struct("timestamp_col", "id_col")
Exemples AUTO CDC
Les exemples suivants illustrent le traitement SCD Type 1 et Type 2 à l’aide d’une source de flux de données modifiées. L’exemple de données crée de nouveaux enregistrements utilisateur, supprime un enregistrement utilisateur et met à jour les enregistrements utilisateur. Dans l’exemple SCD Type 1, les dernières UPDATE opérations arrivent en retard et sont supprimées de la table cible, ce qui illustre la gestion des événements hors séquence.
Voici les enregistrements d’entrée utilisés dans ces exemples. Ces données sont créées en exécutant la requête dans la section Créer des exemples de données .
| userId | nom | city | opération | Numéro de séquence |
|---|---|---|---|---|
| 124 | Raul | Oaxaca | INSERT | 1 |
| 123 | Isabel | Monterrey | INSERT | 1 |
| 125 | Mercedes | Tijuana | INSERT | 2 |
| 126 | Lys | Cancun | INSERT | 2 |
| 123 | zéro | zéro | Supprimer | 6 |
| 125 | Mercedes | Guadalajara | UPDATE | 6 |
| 125 | Mercedes | Mexicali | UPDATE | 5 |
| 123 | Isabel | Chihuahua | UPDATE | 5 |
Si vous supprimez les marques de commentaire de la ligne finale dans l’exemple de requête de génération de données, celle-ci insère l’enregistrement suivant, qui indique de tronquer la table (vider la table) lorsque sequenceNum=3 :
| userId | nom | city | opération | Numéro de séquence |
|---|---|---|---|---|
| zéro | zéro | zéro | TRONQUER | 3 |
Note
Tous les exemples suivants incluent des options pour spécifier à la fois DELETE et TRUNCATE des opérations, mais chacune est facultative.
Créer des données d’exemple
Exécutez les instructions suivantes pour créer un exemple de jeu de données. Ce code n’est pas destiné à être exécuté dans le cadre d’une définition de pipeline. Exécutez-le à partir du dossier d’exploration de votre pipeline, plutôt que du dossier des transformations.
CREATE SCHEMA IF NOT EXISTS main.cdc_tutorial;
CREATE TABLE main.cdc_tutorial.users_cdf
AS SELECT
col1 AS userId,
col2 AS name,
col3 AS city,
col4 AS operation,
col5 AS sequenceNum
FROM (
VALUES
-- Initial load.
(124, "Raul", "Oaxaca", "INSERT", 1),
(123, "Isabel", "Monterrey", "INSERT", 1),
-- New users.
(125, "Mercedes", "Tijuana", "INSERT", 2),
(126, "Lily", "Cancun", "INSERT", 2),
-- Isabel is removed from the system and Mercedes moved to Guadalajara.
(123, null, null, "DELETE", 6),
(125, "Mercedes", "Guadalajara", "UPDATE", 6),
-- This batch of updates arrived out of order. The batch at sequenceNum 6 is the final state.
(125, "Mercedes", "Mexicali", "UPDATE", 5),
(123, "Isabel", "Chihuahua", "UPDATE", 5)
-- Uncomment to test TRUNCATE.
-- ,(null, null, null, "TRUNCATE", 3)
);
Traiter les mises à jour SCD Type 1
SCD Type 1 conserve uniquement la dernière version de chaque enregistrement. L’exemple suivant lit le flux des changements de données créé ci-dessus et applique les changements à une table de streaming cible. Vous avez besoin d’un pipeline pour exécuter ce code. Consultez Développer et déboguer des pipelines ETL avec l’éditeur de pipelines Lakeflow.
Python
from pyspark import pipelines as dp
from pyspark.sql.functions import col, expr
@dp.view
def users():
return spark.readStream.table("main.cdc_tutorial.users_cdf")
dp.create_streaming_table("users_current")
dp.create_auto_cdc_flow(
target = "users_current",
source = "users",
keys = ["userId"],
sequence_by = col("sequenceNum"),
apply_as_deletes = expr("operation = 'DELETE'"),
apply_as_truncates = expr("operation = 'TRUNCATE'"),
except_column_list = ["operation", "sequenceNum"],
stored_as_scd_type = 1
)
SQL
CREATE OR REFRESH STREAMING TABLE users_current;
CREATE FLOW apply_cdc AS AUTO CDC INTO
users_current
FROM
stream(main.cdc_tutorial.users_cdf)
KEYS
(userId)
APPLY AS DELETE WHEN
operation = "DELETE"
APPLY AS TRUNCATE WHEN
operation = "TRUNCATE"
SEQUENCE BY
sequenceNum
COLUMNS * EXCEPT
(operation, sequenceNum)
STORED AS
SCD TYPE 1;
Après avoir exécuté l’exemple SCD Type 1, la table cible contient les enregistrements suivants :
| userId | nom | city |
|---|---|---|
| 124 | Raul | Oaxaca |
| 125 | Mercedes | Guadalajara |
| 126 | Lys | Cancun |
L’utilisateur 123 (Isabel) a été supprimé et n’apparaît pas. L’utilisateur 125 (Mercedes) affiche uniquement la dernière ville (Guadalajara), car SCD Type 1 remplace les valeurs précédentes. La version antérieure UPDATE a été supprimée à sequenceNum=5, car une mise à jour ultérieure a été reçue à sequenceNum=6.
Après avoir exécuté l’exemple avec l’enregistrement TRUNCATE non commenté, la table est vidée à sequenceNum=3. Cela signifie que les enregistrements 124 et 126 ne figurent pas dans la table et que la table cible finale contient uniquement l’enregistrement suivant :
| userId | nom | city |
|---|---|---|
| 125 | Mercedes | Guadalajara |
Traiter les mises à jour SCD de type 2
SCD Type 2 conserve un historique complet des modifications en créant de nouvelles lignes pour chaque version d’un enregistrement, avec __START_AT et __END_AT des colonnes indiquant quand chaque version était active.
Python
from pyspark import pipelines as dp
from pyspark.sql.functions import col, expr
@dp.view
def users():
return spark.readStream.table("main.cdc_tutorial.users_cdf")
dp.create_streaming_table("users_history")
dp.create_auto_cdc_flow(
target = "users_history",
source = "users",
keys = ["userId"],
sequence_by = col("sequenceNum"),
apply_as_deletes = expr("operation = 'DELETE'"),
except_column_list = ["operation", "sequenceNum"],
stored_as_scd_type = "2"
)
SQL
CREATE OR REFRESH STREAMING TABLE users_history;
CREATE FLOW apply_cdc AS AUTO CDC INTO
users_history
FROM
stream(main.cdc_tutorial.users_cdf)
KEYS
(userId)
APPLY AS DELETE WHEN
operation = "DELETE"
SEQUENCE BY
sequenceNum
COLUMNS * EXCEPT
(operation, sequenceNum)
STORED AS
SCD TYPE 2;
Après avoir exécuté l’exemple SCD Type 2, la table cible contient les enregistrements suivants :
| userId | nom | city | __START_AT | __END_AT |
|---|---|---|---|---|
| 123 | Isabel | Monterrey | 1 | 5 |
| 123 | Isabel | Chihuahua | 5 | 6 |
| 124 | Raul | Oaxaca | 1 | zéro |
| 125 | Mercedes | Tijuana | 2 | 5 |
| 125 | Mercedes | Mexicali | 5 | 6 |
| 125 | Mercedes | Guadalajara | 6 | zéro |
| 126 | Lys | Cancun | 2 | zéro |
La table conserve l’historique complet. L’utilisateur 123 a deux versions (terminées à la séquence 6 lors de la suppression). L’utilisateur 125 a trois versions montrant les changements de ville. Les enregistrements avec __END_AT = null sont actuellement actifs.
Suivre un sous-ensemble de colonnes avec SCD Type 2
Par défaut, SCD Type 2 crée une nouvelle version chaque fois qu’une valeur de colonne change. Vous pouvez spécifier un sous-ensemble de colonnes à suivre, afin que les modifications apportées à d’autres colonnes mettent à jour la version actuelle en place plutôt que de générer un nouvel enregistrement d’historique.
L’exemple suivant exclut la colonne city du suivi de l’historique :
Python
from pyspark import pipelines as dp
from pyspark.sql.functions import col, expr
@dp.view
def users():
return spark.readStream.table("main.cdc_tutorial.users_cdf")
dp.create_streaming_table("users_history")
dp.create_auto_cdc_flow(
target = "users_history",
source = "users",
keys = ["userId"],
sequence_by = col("sequenceNum"),
apply_as_deletes = expr("operation = 'DELETE'"),
except_column_list = ["operation", "sequenceNum"],
stored_as_scd_type = "2",
track_history_except_column_list = ["city"]
)
SQL
CREATE OR REFRESH STREAMING TABLE users_history;
CREATE FLOW apply_cdc AS AUTO CDC INTO
users_history
FROM
stream(main.cdc_tutorial.users_cdf)
KEYS
(userId)
APPLY AS DELETE WHEN
operation = "DELETE"
SEQUENCE BY
sequenceNum
COLUMNS * EXCEPT
(operation, sequenceNum)
STORED AS
SCD TYPE 2
TRACK HISTORY ON * EXCEPT
(city)
Étant donné que les changements de city ne sont pas suivis, les mises à jour de cette colonne écrasent la ligne actuelle au lieu de créer une nouvelle version. La table cible contient les enregistrements suivants :
| userId | nom | city | __START_AT | __END_AT |
|---|---|---|---|---|
| 123 | Isabel | Chihuahua | 1 | 6 |
| 124 | Raul | Oaxaca | 1 | zéro |
| 125 | Mercedes | Guadalajara | 2 | zéro |
| 126 | Lys | Cancun | 2 | zéro |
Traiter les mises à jour bitemporelles
Les tables bitemporelles suivent quand chaque changement a pris effet (temps métier) et quand le système l’a enregistré (temps système). Utilisez SEQUENCE BY pour la colonne du temps métier et SYSTEM SEQUENCE BY (system_sequence_by en Python) pour la colonne du temps système. Les cibles bitemporelles nécessitent les deux. Les extraits suivants ne montrent que la définition du flux. Pour le code complet du pipeline, voir Exemple : Suivre les rôles des employés avec un CDC bitemporel AUTO.
Python
dp.create_auto_cdc_flow(
target = "employees_bitemporal",
source = "employees",
keys = ["employeeId"],
sequence_by = "effectiveDate",
system_sequence_by = "recordedAt",
apply_as_deletes = expr("operation = 'DELETE'"),
except_column_list = ["operation"],
stored_as_scd_type = "bitemporal"
)
SQL
CREATE FLOW apply_cdc AS AUTO CDC INTO employees_bitemporal
FROM stream(main.cdc_tutorial.employees_cdf)
KEYS (employeeId)
APPLY AS DELETE WHEN operation = "DELETE"
SEQUENCE BY effectiveDate
SYSTEM SEQUENCE BY recordedAt
COLUMNS * EXCEPT (operation)
STORED AS BITEMPORAL;
Pour les colonnes que les cibles bitemporelles ajoutent, ainsi qu’un parcours complet avec des données d’exemple, des mises à jour, corrections et requêtes hors ordre, voir Bitemporal AUTO CDC.
EXEMPLES D’AUTO CDC À PARTIR D’INSTANTANÉS
Les sections suivantes fournissent des exemples d’utilisation AUTO CDC FROM SNAPSHOT pour traiter des instantanés dans des tables cibles SCD Type 1 ou Type 2. Pour plus d’informations sur l’utilisation de cette API, consultez Capture des modifications de données et instantanés.
Les exemples de cette section incluent des implémentations Python et SQL. Pour une syntaxe SQL complète, voir CREATE FLOW (pipelines).
Exemple : Traiter des instantanés périodiques
Utilisez cette approche lorsqu’un système source exporte un instantané complet selon un calendrier régulier, par exemple un fichier toutes les heures, et que les instantanés arrivent dans l’ordre. Dans cet exemple, chaque instantané est un fichier CSV dont le nom inclut la date et l’heure de l’exportation, comme users_2026-10-15-09.csv.
- L’implémentation SQL utilise une
WITH VERSIONrequête pour trouver le fichier snapshot suivant et utilise la date et l’heure dans le nom du fichier comme version snapshot. Le pipeline suit la dernière version traitée. - L’implémentation Python utilise une fonction de version pour trouver le fichier instantané suivant et utilise la date et l’heure dans le nom du fichier comme version de l’instantané.
Vous pouvez aussi lire des instantanés provenant d’autres types de sources, comme une table en Python ou SQL, ou une connexion JDBC en Python. Voir Initialiser une cible vide à partir d’un seul instantané.
Étape 1 : Créer des fichiers d’instantanés d’exemple
Créez un volume et écrivez-y deux fichiers d’instantané horaires. Exécutez le code suivant depuis un notebook dans le explorations dossier de votre pipeline :
spark.sql("CREATE SCHEMA IF NOT EXISTS main.cdc_tutorial")
spark.sql("CREATE VOLUME IF NOT EXISTS main.cdc_tutorial.hourly_snapshots")
dbutils.fs.put(
"/Volumes/main/cdc_tutorial/hourly_snapshots/users_2026-10-15-09.csv",
"userId,city\n1,Oaxaca\n2,Monterrey\n3,Tijuana\n",
overwrite=True
)
dbutils.fs.put(
"/Volumes/main/cdc_tutorial/hourly_snapshots/users_2026-10-15-10.csv",
"userId,city\n2,Carmel\n3,Los Angeles\n4,Death Valley\n6,Kings Canyon\n",
overwrite=True
)
Étape 2 : Exécuter AUTO CDC À PARTIR DU SNAPSHOT
Vous avez besoin d’un pipeline pour exécuter le code à cette étape. Consultez Développer et déboguer des pipelines ETL avec l’éditeur de pipelines Lakeflow.
Dans un pipeline, créez un nouveau fichier Python ou SQL dans le transformations dossier, ajoutez le code suivant, puis exécutez le pipeline :
Python
import re
from typing import Optional, Tuple
from pyspark import pipelines as dp
from pyspark.sql import DataFrame
snapshot_dir = "/Volumes/main/cdc_tutorial/hourly_snapshots/"
snapshot_pattern = re.compile(r"users_([0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{2})[.]csv")
def get_next_snapshot(
latest_snapshot_version: Optional[str]
) -> Optional[Tuple[DataFrame, str]]:
snapshots = []
for file in dbutils.fs.ls(snapshot_dir):
match = snapshot_pattern.fullmatch(file.name)
if match:
version = match.group(1)
if latest_snapshot_version is None or version > latest_snapshot_version:
snapshots.append((version, file.path))
if not snapshots:
return None
next_version, snapshot_path = min(snapshots)
snapshot = (
spark.read
.format("csv")
.option("header", True)
.schema("userId INT, city STRING")
.load(snapshot_path)
)
return (snapshot, next_version)
dp.create_streaming_table("target")
dp.create_auto_cdc_from_snapshot_flow(
target = "target",
source = get_next_snapshot,
keys = ["userId"],
stored_as_scd_type = 2
)
SQL
CREATE OR REFRESH STREAMING TABLE target;
CREATE FLOW target_snapshot_flow AS
AUTO CDC INTO target
-- Read the snapshot file selected by WITH VERSION.
FROM SNAPSHOT (
SELECT CAST(userId AS INT) AS userId, city
FROM read_files(
'/Volumes/main/cdc_tutorial/hourly_snapshots/',
format => 'csv',
header => true
)
WHERE _metadata.file_name = CONCAT(
'users_',
(SELECT version FROM current_snapshot_version()),
'.csv'
)
)
-- Select the earliest snapshot file that is newer than the last processed version.
-- The version is the fixed-width date and hour string in the file name.
WITH VERSION (
WITH snapshot_files AS (
SELECT regexp_extract(
path,
'users_([0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{2})[.]csv$',
1
) AS version
FROM list_files('/Volumes/main/cdc_tutorial/hourly_snapshots/')
WHERE path RLIKE 'users_[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{2}[.]csv$'
)
SELECT version
FROM snapshot_files
WHERE (
NOT EXISTS (SELECT 1 FROM last_snapshot_version())
OR version > (SELECT version FROM last_snapshot_version())
)
ORDER BY version
LIMIT 1
)
KEYS (userId)
STORED AS SCD TYPE 2;
Lancez le pipeline. Pendant la mise à jour, le flux traite l’instantané de 09:00 suivi de celui de 10:00.
AUTO CDC FROM SNAPSHOT compare les deux instantanés et détecte que l’utilisateur 1 a été supprimé, que les utilisateurs 2 et 3 ont été mis à jour, et que les utilisateurs 4 et 6 ont été insérés. Les versions instantanées analysées à partir des noms de fichiers sont stockées dans les colonnes __START_AT et __END_AT.
Avec SCD Type 2, la table cible contient les enregistrements suivants :
| userId | city | __START_AT | __END_AT |
|---|---|---|---|
| 1 | Oaxaca | 2026-10-15-09 | 2026-10-15-10 |
| 2 | Monterrey | 2026-10-15-09 | 2026-10-15-10 |
| 2 | Carmel | 2026-10-15-10 | zéro |
| 3 | Tijuana | 2026-10-15-09 | 2026-10-15-10 |
| 3 | Los Angeles | 2026-10-15-10 | zéro |
| 4 | Vallée de la mort | 2026-10-15-10 | zéro |
| 6 | Kings Canyon | 2026-10-15-10 | zéro |
L’utilisateur 1 a été supprimé. Les utilisateurs 2 et 3 ont chacun deux versions affichant leurs changements de ville. Les utilisateurs 4 et 6 ont été récemment insérés.
Note
Pour utiliser SCD Type 1 au lieu de SCD Type 2, configuré stored_as_scd_type=1 en Python ou STORED AS SCD TYPE 1 en SQL. La table cible SCD Type 1 n’inclut pas les colonnes __START_AT et __END_AT.
Avec SCD Type 1, la table cible ne montre que l’état actuel :
| userId | city |
|---|---|
| 2 | Carmel |
| 3 | Los Angeles |
| 4 | Vallée de la mort |
| 6 | Kings Canyon |
Étape 3 : Simuler un nouvel instantané et réexécuter
Écrivez un autre fichier d’instantané horaire pour simuler l’arrivée d’une nouvelle exportation. Exécutez ce code à partir d’un notebook dans le dossier explorations de votre pipeline :
dbutils.fs.put(
"/Volumes/main/cdc_tutorial/hourly_snapshots/users_2026-10-15-11.csv",
"userId,city\n2,Carmel\n3,San Diego\n4,Death Valley\n6,Kings Canyon\n7,Joshua Tree\n",
overwrite=True
)
Exécuter de nouveau le pipeline. Le flux ne sélectionne que l’instantané de 11 h 00, car les versions précédentes ont déjà été traitées. L’utilisateur 3 est mis à jour, l’utilisateur 7 est inséré, et les autres enregistrements restent inchangés.
Si plusieurs fichiers horaires arrivent entre les mises à jour du pipeline, les deux implementations traitent chaque fichier disponible dans l’ordre des versions lors de la mise à jour suivante.
Exemple : Initialiser une cible vide à partir d’un seul instantané
Utilisez cette approche pour initialiser une nouvelle cible vide à partir d’un snapshot faisant autorité. Définissez once=True en Python ou utilisez le mot-clé ONCE en SQL pour que ce soit un flux exécuté une seule fois. Après que le flux a été validé, les mises à jour incrémentales suivantes du pipeline l’ignorent. Un rafraîchissement complet efface la cible et relance le flux.
Cet exemple utilise une table comme source d’instantané et stocke l’état actuel avec SCD Type 1. Pour ajouter un instantané à une cible qui reçoit également des événements d’un AUTO CDC flux, voir Ajouter un remplissage à une table AUTO CDC SCD Type 1.
Étape 1 : Créer l’instantané source
Créez un tableau contenant l’état actuel complet de la source :
CREATE SCHEMA IF NOT EXISTS main.cdc_tutorial;
CREATE OR REPLACE TABLE main.cdc_tutorial.initial_users (
userId INT,
city STRING
);
INSERT INTO main.cdc_tutorial.initial_users VALUES
(1, 'Oaxaca'),
(2, 'Monterrey'),
(3, 'Tijuana');
Étape 2 : Créer le flux d’instantané ponctuel
Dans un pipeline, créez un fichier Python ou SQL dans le transformations dossier, ajoutez le code suivant, puis exécutez le pipeline. Consultez Développer et déboguer des pipelines ETL avec l’éditeur de pipelines Lakeflow.
Python
from pyspark import pipelines as dp
dp.create_streaming_table("users")
dp.create_auto_cdc_from_snapshot_flow(
target = "users",
source = "main.cdc_tutorial.initial_users",
keys = ["userId"],
stored_as_scd_type = 1,
once = True
)
SQL
CREATE OR REFRESH STREAMING TABLE users;
CREATE FLOW initial_users_flow AS
AUTO CDC ONCE INTO users
FROM SNAPSHOT (
SELECT userId, city
FROM main.cdc_tutorial.initial_users
)
KEYS (userId)
STORED AS SCD TYPE 1;
Utilisez une source JDBC en Python
Pour initialiser la cible à partir d’une connexion JDBC sur le calcul classique, définissez une vue qui lit la table source et utilisez le nom de la vue comme source argument :
@dp.view(name="initial_users")
def initial_users():
return (spark.read
.format("jdbc")
.option("url", "<jdbc-url>")
.option("dbtable", "<table-name>")
.option("user", "<username>")
.option("password", "<password>")
.load()
)
Définir source = "initial_users" et once = True quand vous créez le flux.
Après la mise à jour, la cible contient les lignes suivantes :
| userId | city |
|---|---|
| 1 | Oaxaca |
| 2 | Monterrey |
| 3 | Tijuana |
Étape 3 : Vérifier le comportement du flux à usage unique
Remplacez les données sources par un autre instantané :
TRUNCATE TABLE main.cdc_tutorial.initial_users;
INSERT INTO main.cdc_tutorial.initial_users VALUES
(2, 'Carmel'),
(3, 'Los Angeles'),
(4, 'Death Valley');
Effectuez une autre mise à jour incrémentale du pipeline. La cible reste inchangée car le flux à usage unique est déjà terminé. Si vous effectuez un rafraîchissement complet, le pipeline nettoie la cible et relance le flux. La cible contient alors le snapshot de remplacement.
Limites
- La colonne de séquencement doit être un type de données triable.
NULLLes valeurs de séquençage ne sont pas prises en charge. - Pour diffuser des données en continu à partir de la cible d’un processus AUTO CDC, lisez son flux de modification. Pour plus d’informations, consultez Lire un flux de données modifiées à partir d’une table cible AUTO CDC.
- Les cibles bitemporelles présentent les limitations suivantes :
- La fonction
AUTO CDC FROM SNAPSHOTn'est pas prise en charge. Pour traiter les instantanés, dérivez d’abord un flux de changements à partir de ceux-ci. Voir Traiter les instantanés avec AUTO CDC bitemporel. - Les flux combinés
AUTO CDC FROM SNAPSHOTetAUTO CDCne sont pas pris en charge. - Les flux multiples
AUTO CDCqui écrivent sur la même cible bitemporelle ne sont pas pris en charge. -
TRACK HISTORY ON(track_history_column_listettrack_history_except_column_listen Python) n’est pas pris en charge. Les cibles bitemporelles suivent l’historique de chaque colonne. -
COLUMNS TO UPDATEetIGNORE NULL UPDATESne sont pas pris en charge. - La fonction
APPLY AS TRUNCATE WHENn'est pas prise en charge.
- La fonction
Ressources supplémentaires
- Capture des données de changement et instantanés : Découvrez les concepts CDC, les instantanés et les types de SCD.
-
Répliquez une table RDBMS externe en utilisant
AUTO CDC: Apprenez à effectuer une hydratation initiale avec unonceflux puis continuez à traiter les modifications. - Rétroremplissage des données historiques avec des pipelines : Apprenez à rétroremplir les cibles append-only et AUTO CDC SCD Type 1.
- AUTO CDC bitemporel : découvrez comment suivre l’historique selon le temps métier et le temps système.
- Sujets avancés AUTO CDC : Apprenez les opérations de changement sur les cibles AUTO CDC, la lecture des flux de données de changement et le traitement des métriques.
- Remontez et rejouez un pipeline : Apprenez à restaurer une cible AUTO CDC à un moment antérieur et à retraiter les modifications.
- Tutoriel : Construire un pipeline ETL en utilisant la capture de données de changement