Les API AUTO CDC : Simplifier la capture des changements de données avec des pipelines
Les pipelines Lakeflow simplifient la capture de données modifiées (CDC) avec les APIs AUTO CDC et AUTO CDC FROM SNAPSHOT. Ces APIs automatisent la complexité du compute de SCD (Slowly Changing Dimensions) de type 1 et de type 2 à partir d'un flux CDC ou d'instantanés de base de données, et l'API AUTO CDC compute également l'historique bitemporel à partir d'un flux CDC. Pour en savoir plus sur le SCD de type 1, le SCD de type 2 et le bitemporel, consultez Capture de données modifiées et instantanés.
Les AUTO CDC APIs remplacent les APPLY CHANGES APIs et ont la même syntaxe. Les APIs APPLY CHANGES sont toujours disponibles, mais Databricks recommande d'utiliser les APIs AUTO CDC à leur place.
L'API que vous utilisez dépend de la source de vos données de modification :
AUTO CDC: Utilisez ceci lorsque la base de données source a un flux CDC activé.AUTO CDCtraite les modifications d'un flux de données de modification (CDF). Il est pris en charge à la fois dans les interfaces SQL et Python du pipeline.AUTO CDC FROM SNAPSHOT: à utiliser lorsque le CDC n’est pas activé sur la base de données source et que seuls des instantanés sont disponibles. Cette API compare les instantanés pour déterminer les changements, puis les traite. Il est pris en charge dans les interfaces SQL et Python du pipeline.
Pour les cibles de type SCD 1, vous pouvez également combiner un flux AUTO CDC FROM SNAPSHOT avec un ou plusieurs flux AUTO CDC. Utilisez ce modèle lorsqu'une source fournit des instantanés périodiques faisant foi et un flux CDC à plus faible latence entre les instantanés.
Les APIs prennent en charge les types de stockage suivants pour les tables cibles :
- SCD de type 1 : Mettez à jour les enregistrements directement. L’historique n’est pas conservé pour les enregistrements mis à jour. Pris en charge par les deux APIs.
- SCD de type 2 : conservez 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 APIs.
- Bitemporel : conserve un historique des enregistrements sur deux timelines : l’heure métier, quand un changement est entré en vigueur, et l’heure système, quand le système l’a enregistré. Pris en charge par
AUTO CDCuniquement. Consultez AUTO CDC bitemporel.
AUTO CDC prend également en charge les mises à jour partielles, où un enregistrement de modification met à jour seulement un sous-ensemble de colonnes. Consultez Appliquer les mises à jour partielles.
Les APIs AUTO CDC ne sont pas prises en charge par Apache Spark Declarative Pipelines.
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.
Utilisez ces APIs pour mettre à jour les tables de vos pipelines en fonction des changements apportés aux données sources. Pour savoir comment enregistrer et query les informations de modification au niveau des lignes pour les tables Delta, consultez Utiliser le flux de données de modification sur Databricks.
Exigences
Pour utiliser les API CDC, votre pipeline doit être configuré pour utiliser Pro les Advanced éditions ou des Lakeflow Pipelines.
Fonctionnement de l'AUTO CDC
Pour effectuer le traitement CDC avec AUTO CDC, créez une table de streaming, puis utilisez l'instruction AUTO CDC ... INTO en 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 une explication du fonctionnement du séquencement et de la logique SCD, consultez Change data capture and snapshots. Consultez les exemples AUTO CDC.
Pour une hydratation initiale à partir d'une source avec un flux de modifications, utilisez AUTO CDC avec un flux once et continuez ensuite à traiter le flux de modifications. Consultez Répliquer une table RDBMS externe à l'aide d'AUTO CDC.
Pour plus de détails sur la syntaxe, consultez AUTO CDC INTO (pipelines) ou create_auto_cdc_flow.
Comment AUTO CDC FROM SNAPSHOT fonctionne
AUTO CDC FROM SNAPSHOT détermine les modifications dans les données source en comparant des instantanés ordonnés. Vous pouvez lire des instantanés directement à partir d’une table Delta, de fichiers de stockage cloud ou de JDBC. Il est pris en charge dans les interfaces SQL et Python du pipeline.
Pour effectuer un traitement de 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 clauseFLOW AUTO CDCintégrée deCREATE STREAMING TABLE. La source est une clauseFROM SNAPSHOT (snapshot_query)obligatoire et une clauseWITH VERSION (version_query)facultative qui sélectionne la version d’instantané suivante à traiter. Consultez 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. Consultez create_auto_cdc_from_snapshot_flow.
Pour plus de détails sur les deux modèles d'ingestion et sur le moment d'utiliser chacun d'eux, consultez Snapshot processing patterns. Consultez les exemples AUTO CDC FROM SNAPSHOT.
Combiner AUTO CDC FROM SNAPSHOT et AUTO CDC
La version d’instantané et la colonne de séquençage CDC forment un domaine d’ordonnancement. Un événement CDC plus récent que le dernier instantané a priorité sur l’instantané. Un instantané plus récent a priorité sur les événements CDC plus anciens et traite les clés absentes de l’instantané comme supprimées à la version de l’instantané. Des é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 SCD de type 1.
- The target has exactly one
AUTO CDC FROM SNAPSHOTflow and one or moreAUTO CDCflows. - Chaque flux
AUTO CDCpossède un nom unique. - Tous les flux utilisent le même nombre de clés dans le même ordre. Les noms de clé du flux d'instantané sont comparés sans distinction de majuscules et de minuscules avec les noms de clé
AUTO CDC. Plusieurs fluxAUTO CDCdoivent utiliser des noms de clé et des casses identiques. - The snapshot version and each CDC sequencing column have exactly the same data type.
- Le flux
AUTO CDC FROM SNAPSHOTne définit pas d’attentes. - Les flux
AUTO CDCn’utilisent pasIGNORE NULL UPDATESou ses variantes de liste de colonnes. - Le pipeline utilise le mode Trigger.
- Si vous ajoutez un flux
AUTO CDCà une cibleAUTO CDC FROM SNAPSHOTexistante, la cible ne doit pas contenir de colonnes utilisateur dont les noms entrent en conflit avec les colonnes systèmeAUTO CDCréservées.
Les flux AUTO CDC et AUTO CDC FROM SNAPSHOT peuvent tous deux utiliser l'interface de pipeline Python ou SQL. Vous pouvez mélanger des flux SQL et Python dans la même cible.
Utilisez once=True en Python ou ONCE en SQL sur le flux AUTO CDC FROM SNAPSHOT pour remplir un instantané une seule fois tandis que les flux AUTO CDC continuent de traiter de nouveaux événements lors des mises à jour ultérieures. Une refresh complète de la cible réexécute le flux d'instantané ponctuel. Pour un exemple complet, voir Ajouter un remplissage à une table AUTO CDC SCD Type 1.
Ce modèle ne prend pas en charge le SCD de type 2 ou les cibles bitemporelles.
Utiliser plusieurs colonnes pour le séquençage
Pour séquencer par plusieurs colonnes (par exemple, un Timestamp et un ID pour départager), utilisez un STRUCT pour les combiner. L'API classe par le premier champ, et en cas d'égalité, prend en compte le second champ, et ainsi de suite.
- SQL
- Python
SEQUENCE BY STRUCT(timestamp_col, id_col)
sequence_by = struct("timestamp_col", "id_col")
Exemples AUTO CDC
Les exemples suivants illustrent le traitement SCD de type 1 et de type 2 à l'aide d'une source de flux de données de modifications. Les données d'échantillon créent de nouveaux enregistrements d'utilisateur, suppriment un enregistrement d'utilisateur et mettent à jour les enregistrements d'utilisateur. Dans l'exemple de SCD de type 1, les UPDATE dernières opérations arrivent en retard et sont supprimées de la table cible, ce qui démontre la gestion des événements désordonnés.
Voici les enregistrements d'entrée utilisés dans ces exemples. Ces données sont créées en exécutant la query dans la section Créer un échantillon de données.
ID utilisateur | Nom | ville | Opérations | sequenceNum |
|---|---|---|---|---|
124 | Raul | Oaxaca | INSÉRER | 1 |
123 | Isabel | Monterrey | INSÉRER | 1 |
125 | Mercedes | Tijuana | INSÉRER | 2 |
126 | Lily | Cancun | INSÉRER | 2 |
123 | nul | nul | Supprimer | 6 |
125 | Mercedes | Guadalajara | Mettre à jour | 6 |
125 | Mercedes | Mexicali | Mettre à jour | 5 |
123 | Isabel | Chihuahua | Mettre à jour | 5 |
Si vous décommentez la dernière ligne dans la query de génération de données d'exemple, cela insère l'enregistrement suivant qui spécifie de tronquer la table (effacer la table) à sequenceNum=3:
ID utilisateur | Nom | ville | Opérations | sequenceNum |
|---|---|---|---|---|
nul | nul | nul | TRONQUER | 3 |
Tous les exemples suivants incluent des options pour spécifier les opérations DELETE et TRUNCATE, mais chacune est facultative.
Créer un échantillon de données
Exécutez les instructions suivantes pour créer un jeu de données d'exemple. 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 qu'à partir du dossier de 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 de type 1
Le SCD de type 1 ne conserve que la dernière version de chaque enregistrement. L’exemple suivant lit les données à partir du flux de données de modification créé ci-dessus et applique les modifications à une cible de table de streaming. Vous avez besoin d’un pipeline pour exécuter ce code. Consultez la section Développer et déboguer des pipelines ETL avec l’éditeur de Lakeflow Pipelines.
- Python
- SQL
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
)
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 de SCD de type 1, la table cible contient les enregistrements suivants :
ID utilisateur | Nom | ville |
|---|---|---|
124 | Raul | Oaxaca |
125 | Mercedes | Guadalajara |
126 | Lily | Cancun |
L'utilisateur 123 (Isabel) a été supprimé et n'apparaît pas. L'utilisateur 125 (Mercedes) ne montre que la dernière ville (Guadalajara) car le SCD de type 1 écrase les valeurs précédentes. L'élément UPDATE précédent à sequenceNum=5 a été abandonné car une mise à jour ultérieure à sequenceNum=6 est arrivée.
Après avoir exécuté l'exemple avec l'enregistrement TRUNCATE non commenté, la table est effacée à sequenceNum=3. Cela signifie que les enregistrements 124 et 126 ne sont pas dans la table, et que la table cible finale contient uniquement l'enregistrement suivant :
ID utilisateur | Nom | ville |
|---|---|---|
125 | Mercedes | Guadalajara |
Traiter les mises à jour SCD de type 2
Le SCD de type 2 préserve un historique complet des modifications en créant de nouvelles lignes pour chaque version d'un enregistrement, avec les colonnes __START_AT et __END_AT indiquant quand chaque version était active.
- Python
- SQL
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"
)
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 de SCD de type 2, la table cible contient les enregistrements suivants :
ID utilisateur | Nom | ville | start | __END_AT |
|---|---|---|---|---|
123 | Isabel | Monterrey | 1 | 5 |
123 | Isabel | Chihuahua | 5 | 6 |
124 | Raul | Oaxaca | 1 | nul |
125 | Mercedes | Tijuana | 2 | 5 |
125 | Mercedes | Mexicali | 5 | 6 |
125 | Mercedes | Guadalajara | 6 | nul |
126 | Lily | Cancun | 2 | nul |
La table conserve l'historique complet. L'utilisateur 123 a deux versions (terminé à la séquence 6 lors de la suppression). L'utilisateur 125 dispose de trois versions présentant des changements de ville. Les enregistrements avec __END_AT = null sont actuellement actifs.
Suivre un sous-ensemble de colonnes avec le SCD de type 2
Par défaut, le SCD de type 2 crée une nouvelle version chaque fois que la valeur d'une colonne change. Vous pouvez spécifier un sous-ensemble de colonnes à suivre, de sorte que les modifications apportées aux autres colonnes mettent à jour la version actuelle sur 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
- SQL
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"]
)
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 modifications de city ne sont pas suivies, les mises à jour de ville écrasent la ligne actuelle au lieu de créer une nouvelle version. La table cible contient les enregistrements suivants :
ID utilisateur | Nom | ville | start | __END_AT |
|---|---|---|---|---|
123 | Isabel | Chihuahua | 1 | 6 |
124 | Raul | Oaxaca | 1 | nul |
125 | Mercedes | Guadalajara | 2 | nul |
126 | Lily | Cancun | 2 | nul |
Traiter les mises à jour bitemporelles
Les tables bitemporelles suivent le moment où chaque modification a pris effet (heure commerciale) et le moment où le système l’a enregistrée (heure système). Utilisez SEQUENCE BY pour la colonne de l’heure commerciale et SYSTEM SEQUENCE BY (system_sequence_by dans Python) pour la colonne de l’heure système. Les cibles bitemporelles nécessitent les deux. Les extraits suivants ne montrent que la définition du flux. Pour obtenir le code complet du pipeline, consultez Exemple : Suivre les rôles des employés avec la CDC AUTO bitemporelle.
- Python
- SQL
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"
)
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 ajoutées par les cibles bitemporelles et une présentation complète avec des données d'exemple, des mises à jour hors séquence, des corrections et des query, consultez la page AUTO CDC bitemporelle.
Exemples d'AUTO CDC FROM SNAPSHOT
Les sections suivantes fournissent des exemples d'utilisation de AUTO CDC FROM SNAPSHOT pour traiter les instantanés dans des tables cibles de type SCD 1 ou SCD 2. Pour plus d'informations sur l'utilisation de cette API, consultez Capture des données modifiées et instantanés.
Les exemples de cette section incluent des implémentations en Python et en SQL. Pour connaître la syntaxe SQL complète, consultez la page 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, tel qu’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 query
WITH VERSIONpour trouver le fichier d'instantané suivant et utilise la date et l'heure dans le nom de fichier comme version d'instantané. Le pipeline suit la dernière version traitée. - L’implémentation Python utilise une fonction de version pour trouver le prochain fichier d’instantané et utilise la date et l’heure dans le nom de fichier comme version d’instantané.
Vous pouvez également lire des instantanés à partir d’autres types de sources, tels qu’une table en Python ou SQL, ou une connexion JDBC en Python. Consultez Initialiser une cible vide à partir d’un instantané.
Étape 1 : créer des exemples de fichiers d'instantané
Créez un volume et écrivez deux fichiers d'instantanés horaires dessus. Exécutez le code suivant à partir d'un notebook dans le dossier explorations 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écutez AUTO CDC FROM SNAPSHOT
Vous avez besoin d’un pipeline pour exécuter le code de cette étape. Voir Développer et déboguer des pipelines ETL avec l’éditeur de LakeFlow Pipelines.
Dans un pipeline, créez un fichier Python ou SQL dans le dossier transformations, ajoutez le code suivant, puis exécutez le pipeline :
- Python
- SQL
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
)
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;
Exécutez le pipeline. Pendant la mise à jour, le flux traite l’instantané de 09 h 00 suivi de l’instantané de 10 h 00. AUTO CDC FROM SNAPSHOT compare les deux instantanés et détecte que l’utilisateur 1 a été supprimé, les utilisateurs 2 et 3 ont été mis à jour et les utilisateurs 4 et 6 ont été insérés. Les versions de l’instantané analysées à partir des noms de fichier sont stockées dans les colonnes __START_AT et __END_AT.
Avec le SCD de type 2, la table cible contient les enregistrements suivants :
ID utilisateur | ville | start | __END_AT |
|---|---|---|---|
1 | Oaxaca | 2026-10-15-09 | 15/10/2026-10 |
2 | Monterrey | 2026-10-15-09 | 15/10/2026-10 |
2 | Carmel | 15/10/2026-10 | nul |
3 | Tijuana | 2026-10-15-09 | 15/10/2026-10 |
3 | Los Angeles | 15/10/2026-10 | nul |
4 | Death Valley | 15/10/2026-10 | nul |
6 | Kings Canyon | 15/10/2026-10 | nul |
L'utilisateur 1 a été supprimé. Les utilisateurs 2 et 3 ont chacun deux versions montrant leurs changements de ville. Les utilisateurs 4 et 6 ont été nouvellement insérés.
Pour utiliser SCD Type 1 au lieu de SCD Type 2, définissez stored_as_scd_type=1 en Python ou STORED AS SCD TYPE 1 en SQL. La table cible SCD Type 1 ne comprend pas les colonnes __START_AT et __END_AT.
Avec le SCD de type 1, la table cible n'affiche que l'état actuel :
ID utilisateur | ville |
|---|---|
2 | Carmel |
3 | Los Angeles |
4 | Death Valley |
6 | Kings Canyon |
Étape 3 : Simulez un nouvel instantané et réexécutez.
É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écutez à nouveau le pipeline. Le flux sélectionne uniquement 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 sont inchangés.
Si plusieurs fichiers horaires arrivent entre les mises à jour du pipeline, les deux implémentations traitent chaque fichier disponible dans l'ordre de version lors de la mise à jour suivante.
Exemple : initialiser une cible vide à partir d'un snapshot
Utilisez cette approche pour initialiser une nouvelle cible vide à partir d’un instantané faisant autorité. Définissez once=True en Python ou utilisez le mot-clé ONCE en SQL pour faire de ce flux un flux unique. Une fois que le flux est correctement commit, les mises à jour incrémentielles ultérieures du pipeline l’ignorent. Un refresh complet efface la cible et exécute à nouveau le flux.
Cet exemple utilise une table comme source d’instantané et stocke l’état actuel avec SCD de type 1. Pour ajouter un instantané à une cible qui reçoit également des événements d'un flux AUTO CDC, voir Ajouter un rattrapage à une table SCD de type 1 AUTO CDC.
Étape 1 : créez l’instantané source
Créez une table qui contient 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 de capture ponctuelle
Dans un pipeline, créez un fichier Python ou SQL dans le dossier transformations, ajoutez le code suivant et exécutez le pipeline. Voir Développer et déboguer des pipelines ETL avec l’éditeur Lakeflow Pipelines.
- Python
- SQL
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
)
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;
Utiliser une source JDBC en Python
Pour initialiser la cible à partir d’une connexion JDBC sur le compute classique, définissez une vue qui lit la table source et utilisez le nom de la vue comme argument source :
@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éfinissez source = "initial_users" et once = True lorsque vous créez le flux.
Une fois la mise à jour terminée, la cible contient les lignes suivantes :
ID utilisateur | ville |
|---|---|
1 | Oaxaca |
2 | Monterrey |
3 | Tijuana |
Étape 3 : Vérifier le comportement du flux unique
Remplacez les données source par un instantané différent :
TRUNCATE TABLE main.cdc_tutorial.initial_users;
INSERT INTO main.cdc_tutorial.initial_users VALUES
(2, 'Carmel'),
(3, 'Los Angeles'),
(4, 'Death Valley');
Exécutez une autre mise à jour de pipeline incrémentiel. La cible reste inchangée car le flux ponctuel est déjà terminé. Si vous exécutez un refresh complet, le pipeline efface la cible et exécute à nouveau le flux. La cible contient alors le snapshot de remplacement.
Limitations
- La colonne de séquencement doit être un type de données triable. Les valeurs de séquencement
NULLne sont pas prises en charge. - Pour Stream des données depuis la cible d'un processus AUTO CDC, lisez à partir de son flux de changements. Pour plus de détails, consultez Lire un flux de données de modification d'une table cible AUTO CDC.
- Les destinations bitemporelles ont les limites suivantes :
AUTO CDC FROM SNAPSHOTn'est pas pris en charge. Pour traiter des instantanés, commencez par en dériver un flux de modifications. Consultez Traiter des instantanés avec AUTO CDC bitemporel.- Les flux
AUTO CDC FROM SNAPSHOTetAUTO CDCcombinés ne sont pas pris en charge. - Plusieurs flux
AUTO CDCqui écrivent vers 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.APPLY AS TRUNCATE WHENn'est pas pris en charge.
Ressources supplémentaires
- Capture des changements de données et instantanés: Apprenez-en davantage sur les concepts de la CDC, les instantanés et les types de SCD.
- Répliquer une table RDBMS externe à l'aide de
AUTO CDC: Découvrez comment effectuer une hydratation initiale avec un pipelineonce, puis continuer à traiter les modifications. - Backfilling historical data with pipelines: découvrez comment effectuer un remplissage rétroactif des cibles append-only et AUTO CDC SCD de type 1.
- CDC AUTO bitemporelle: Apprenez à suivre l’historique selon l’heure commerciale et l’heure système.
- Rubriques avancées sur AUTO CDC: découvrez 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.
- Revenir en arrière et rejouer un pipeline: découvrez comment restaurer une cible AUTO CDC à un point antérieur dans le temps et retraiter les modifications.
- Tutoriel : Construire un pipeline ETL en utilisant la capture de données modifiées