Les APIs AUTO CDC : Simplifiez la capture des modifications de données grâce aux pipelines

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 CDC traite 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 CDC uniquement. 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 SNAPSHOT de l’instruction CREATE FLOW ou la clause intégrée FLOW AUTO CDC de CREATE STREAMING TABLE. La source est une clause FROM SNAPSHOT (snapshot_query) requise et une clause WITH 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 SNAPSHOT flux et un ou plusieurs AUTO CDC flux.
  • Chaque AUTO CDC flux 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 multiples AUTO CDC doivent 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 SNAPSHOT flow ne définit pas les attentes.
  • Les AUTO CDC flux n’utilisent pas IGNORE NULL UPDATES ni ses variantes de liste de colonnes.
  • Le pipeline utilise le mode déclenché.
  • Si vous ajoutez un AUTO CDC flux à une cible existante AUTO 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ées AUTO 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 VERSION requê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. NULL Les 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 SNAPSHOT n'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 SNAPSHOT et AUTO CDC ne sont pas pris en charge.
    • Les flux multiples AUTO CDC qui écrivent sur la même cible bitemporelle ne sont pas pris en charge.
    • TRACK HISTORY ON(track_history_column_listet track_history_except_column_list en Python) n’est pas pris en charge. Les cibles bitemporelles suivent l’historique de chaque colonne.
    • COLUMNS TO UPDATE et IGNORE NULL UPDATES ne sont pas pris en charge.
    • La fonction APPLY AS TRUNCATE WHEN n'est pas prise en charge.

Ressources supplémentaires