APIs AUTO CDC : Simplifique a captura de dados de alterações (CDC) com pipeline
LakeFlow Pipelines simplificam a captura de dados de alterações (CDC) com as APIs AUTO CDC e AUTO CDC FROM SNAPSHOT. Essas APIs automatizam a complexidade de calcular dimensões que mudam lentamente (SCD) do tipo 1 e do tipo 2 a partir de um feed de CDC ou de Snapshot de banco de dados, e a API AUTO CDC também calcula a história bitemporal a partir de um feed de CDC. Para saber mais sobre SCD Tipo 1, SCD Tipo 2 e bitemporalidade, consulte captura de dados de alterações (CDC) e Snapshots.
As APIs AUTO CDC substituem as APIs APPLY CHANGES e têm a mesma sintaxe. As APIs APPLY CHANGES ainda estão disponíveis, mas a Databricks recomenda o uso das APIs AUTO CDC em seu lugar.
A API que você utiliza depende da origem dos seus dados de alteração:
AUTO CDC: Use isso quando o banco de dados de origem tiver um feed CDC ativado.AUTO CDCprocessa alterações de um feed de dados de alteração (CDF). É compatível com as interfaces SQL e Python do pipeline.AUTO CDC FROM SNAPSHOT: Use isto quando o CDC não estiver habilitado no banco de dados de origem e somente Snapshots estiverem disponíveis. Esta API compara snapshots para determinar as mudanças e, em seguida, os processa. Ele é compatível com as interfaces de SQL e Python do pipeline.
Para destinos do SCD Tipo 1, você também pode combinar um fluxo AUTO CDC FROM SNAPSHOT com um ou mais fluxos AUTO CDC. Use este padrão quando uma fonte fornecer Snapshot autoritativos periódicos e um feed de CDC de menor latência entre os Snapshot.
As APIs oferecem suporte aos seguintes tipos de armazenamento para tabelas de destino:
- SCD tipo 1 : Atualize registros diretamente. A história não é retida para registros atualizados. Compatível com ambas as APIs.
- SCD tipo 2 : Mantenha uma história de registros, seja em todas as atualizações ou em atualizações de um conjunto específico de colunas. Compatível com ambas as APIs.
- Bitemporal : Retém uma história de registros em duas linhas do tempo: tempo comercial, quando uma alteração entra em vigor, e tempo do sistema, quando o sistema a registra. Compatível apenas com
AUTO CDC. Consulte Bitemporal AUTO CDC.
AUTO CDC também oferece suporte a atualizações parciais, onde um registro de alteração atualiza apenas um subconjunto de colunas. Consulte Aplicar atualizações parciais.
As APIs AUTO CDC não são suportadas pelo pipeline declarativo Apache Spark .
Para sintaxe e outras referências, consulte AUTO CDC INTO (pipeline), create_auto_cdc_flow e create_auto_cdc_from_snapshot_flow.
Use estas APIs para atualizar tabelas em seus pipelines com base nas alterações nos dados de origem. Para saber como registrar e fazer query de informações de alteração em nível de linha para tabelas Delta, consulte Usar o feed de dados de alteração no Databricks.
Requisitos
Para usar as APIs do CDC, seu pipeline deve ser configurado para usar as Pro ou Advanced edições do LakeFlow Pipelines.
Como funciona o AUTO CDC
Para realizar o processamento CDC com AUTO CDC, crie uma tabela de transmissão e use a instrução AUTO CDC ... INTO em SQL ou a função create_auto_cdc_flow() em Python para especificar a origem, a chave e a sequência para o feed de alterações. Para obter uma explicação de como funcionam o sequenciamento e a lógica SCD , consulte captura de dados de alterações (CDC) e Snapshot. Veja os exemplos do AUTO CDC.
Para hidratação inicial a partir de uma fonte com alimentação de mudança, use AUTO CDC com um fluxo once e continue processando a alimentação de mudança. Consulte Replicar uma tabela RDBMS externa usando o AUTO CDC.
Para detalhes de sintaxe, consulte AUTO CDC INTO (pipeline) ou create_auto_cdc_flow.
Como funciona o AUTO CDC do Snapshot
AUTO CDC FROM SNAPSHOT determines changes in source data by comparing in-order Snapshot. You can read snapshots from a Delta table, cloud storage files, or JDBC directly. It is supported in both the pipeline SQL and Python interfaces.
Para executar o processamento CDC com AUTO CDC FROM SNAPSHOT, crie uma tabela de transmissão e, em seguida, defina o fluxo:
- In SQL, use the
AUTO CDC ... FROM SNAPSHOTform of theCREATE FLOWstatement or the embeddedFLOW AUTO CDCclause ofCREATE STREAMING TABLE. The source is a requiredFROM SNAPSHOT (snapshot_query)clause and an optionalWITH VERSION (version_query)clause that selects the next snapshot version to process. See CREATE FLOW (pipelines). - No Python, use a função
create_auto_cdc_from_snapshot_flow()para especificar o Snapshot, as chaves (key) e outros argumentos. Consulte create_auto_cdc_from_snapshot_flow.
Para obter detalhes sobre os dois padrões de ingestão e quando usar cada um, consulte Padrões de processamento de snapshot. Consulte os exemplos de AUTO CDC FROM SNAPSHOT.
Combinar o AUTO CDC FROM SNAPSHOT e o AUTO CDC
A versão do snapshot e a coluna de sequenciamento de CDC formam um domínio de ordenação. Um evento de CDC mais recente do que o último snapshot tem precedência sobre o snapshot. Um snapshot mais recente tem precedência sobre eventos de CDC mais antigos e trata as chaves ausentes no snapshot como excluídas na versão do snapshot. Eventos de CDC mais recentes podem preservar ou restaurar essas key.
Um destino unificado deve atender aos seguintes requisitos:
- The target uses SCD Type 1.
- O destino tem exatamente um fluxo
AUTO CDC FROM SNAPSHOTe um ou mais fluxosAUTO CDC. - Cada fluxo
AUTO CDCtem um nome exclusivo. - Todos os fluxos usam o mesmo número de keys na mesma ordem. Os nomes de key do fluxo de snapshot são comparados sem diferenciação de maiúsculas e minúsculas com os nomes de key de
AUTO CDC. Vários fluxosAUTO CDCdevem usar nomes de key e maiúsculas e minúsculas idênticos. - A versão do snapshot e cada coluna de sequenciamento do CDC têm exatamente o mesmo tipo de dados.
- O fluxo
AUTO CDC FROM SNAPSHOTnão define expectativas. - The
AUTO CDCflows do not useIGNORE NULL UPDATESor its column-list variants. - O pipeline usa o modo Trigger.
- If you add an
AUTO CDCflow to an existingAUTO CDC FROM SNAPSHOTtarget, the target must not contain user columns whose names conflict with reservedAUTO CDCsystem columns.
Os fluxos AUTO CDC e AUTO CDC FROM SNAPSHOT podem usar a interface de pipeline em Python ou SQL. Você pode misturar fluxos em SQL e Python no mesmo destino.
Use once=True em Python ou ONCE em SQL no fluxo AUTO CDC FROM SNAPSHOT para preencher um snapshot uma vez, enquanto os fluxos AUTO CDC continuam processando novos eventos em atualizações subsequentes. Uma refresh completa do destino reexecuta o fluxo de Snapshot de uso único. Para ver um exemplo completo, consulte Adicionar um preenchimento retroativo a uma tabela AUTO CDC SCD Tipo 1.
This pattern does not support SCD Type 2 or bitemporal targets.
Use várias colunas para sequenciamento
Para sequenciar por várias colunas (por exemplo, um carimbo de data/hora e um ID para desempatar), use STRUCT para combiná-las. A API ordena os resultados pelo primeiro campo e, em caso de empate, considera o segundo campo, e assim por diante.
- SQL
- Python
SEQUENCE BY STRUCT(timestamp_col, id_col)
sequence_by = struct("timestamp_col", "id_col")
Exemplos de AUTO CDC
Os exemplos a seguir demonstram o processamento de SCD Tipo 1 e Tipo 2 usando uma fonte de dados de alteração. Os dados de exemplo criam novos registros de usuário, excluem registros de usuário e atualizam registros de usuário. No exemplo SCD Tipo 1, as últimas operações UPDATE chegam atrasadas e são descartadas da tabela de destino, demonstrando o tratamento de eventos fora de ordem.
A seguir, estão os registros de entrada usados nestes exemplos. Esses dados são criados executando a consulta na seção Criar dados de exemplo .
userId | name | city | operation | sequenceNum |
|---|---|---|---|---|
124 | Raul | Oaxaca | INSERT | 1 |
123 | Isabel | Monterrey | INSERT | 1 |
125 | Mercedes | Tijuana | INSERT | 2 |
126 | Lily | Cancun | INSERT | 2 |
123 | null | null | DELETE | 6 |
125 | Mercedes | Guadalajara | UPDATE | 6 |
125 | Mercedes | Mexicali | UPDATE | 5 |
123 | Isabel | Chihuahua | UPDATE | 5 |
Se você remover o comentário da última linha na consulta de geração de dados de exemplo, será inserido o seguinte registro que especifica o truncamento da tabela (limpeza da tabela) em sequenceNum=3:
userId | name | city | operation | sequenceNum |
|---|---|---|---|---|
null | null | null | TRUNCATE | 3 |
Todos os exemplos a seguir incluem opções para especificar as operações DELETE e TRUNCATE , mas cada uma é opcional.
Criar dados de exemplo
Execute as seguintes instruções para criar um dataset de exemplo. Este código não se destina a ser executado como parte de uma definição pipeline . execute-o a partir da pasta de exploração do seu pipeline, em vez da pasta de transformações.
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)
);
Atualizações do Processo SCD Tipo 1
O SCD Type 1 mantém apenas a versão mais recente de cada registro. O exemplo a seguir faz a leitura do feed de dados de alteração criado acima e aplica as alterações a um destino de tabela de streaming. Você precisa de um pipeline para executar este código. Consulte Develop and debug ETL pipelines with the Lakeflow Pipelines Editor.
- 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;
Após executar o exemplo do SCD tipo 1, a tabela de destino contém os seguintes registros:
userId | name | city |
|---|---|---|
124 | Raul | Oaxaca |
125 | Mercedes | Guadalajara |
126 | Lily | Cancun |
O usuário 123 (Isabel) foi excluído e não aparece mais. O usuário 125 (Mercedes) mostra apenas a cidade mais recente (Guadalajara) porque o SCD Tipo 1 sobrescreve os valores anteriores. O UPDATE anterior em sequenceNum=5 foi removido porque uma atualização posterior em sequenceNum=6 chegou.
Após executar o exemplo com o registro TRUNCATE descomentado, a tabela é limpa em sequenceNum=3. Isso significa que os registros 124 e 126 não estão na tabela, e a tabela de destino final contém apenas o seguinte registro:
userId | name | city |
|---|---|---|
125 | Mercedes | Guadalajara |
Atualizações do Processo SCD Tipo 2
SCD Tipo 2 preserva um histórico completo de alterações, criando novas linhas para cada versão de um registro, com colunas __START_AT e __END_AT indicando quando cada versão estava ativa.
- 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;
Após executar o exemplo do SCD tipo 2, a tabela de destino contém os seguintes registros:
userId | name | city | __START_AT | __END_AT |
|---|---|---|---|---|
123 | Isabel | Monterrey | 1 | 5 |
123 | Isabel | Chihuahua | 5 | 6 |
124 | Raul | Oaxaca | 1 | null |
125 | Mercedes | Tijuana | 2 | 5 |
125 | Mercedes | Mexicali | 5 | 6 |
125 | Mercedes | Guadalajara | 6 | null |
126 | Lily | Cancun | 2 | null |
A mesa preserva toda a história. O usuário 123 possui duas versões (terminada na sequência 6 quando excluída). O usuário 125 possui três versões que mostram alterações na cidade. Registros com __END_AT = null estão atualmente ativos.
Rastreie um subconjunto de colunas com SCD Tipo 2.
Por default, SCD Tipo 2 cria uma nova versão sempre que o valor de qualquer coluna é alterado. Você pode especificar um subconjunto de colunas para rastrear, de forma que as alterações em outras colunas atualizem a versão atual no mesmo local, em vez de gerar um novo registro no histórico.
O exemplo a seguir exclui a coluna city da história acompanhamento:
- 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)
Como as alterações city não são rastreadas, as atualizações de cidade sobrescrevem a linha atual em vez de criar uma nova versão. A tabela de destino contém os seguintes registros:
userId | name | city | __START_AT | __END_AT |
|---|---|---|---|---|
123 | Isabel | Chihuahua | 1 | 6 |
124 | Raul | Oaxaca | 1 | null |
125 | Mercedes | Guadalajara | 2 | null |
126 | Lily | Cancun | 2 | null |
Processar atualizações bitemporais
Tabelas bitemporais rastreiam quando cada alteração entrou em vigor (tempo de negócios) e quando o sistema a registrou (tempo do sistema). Use SEQUENCE BY para a coluna de tempo de negócios e SYSTEM SEQUENCE BY (system_sequence_by em Python) para a coluna de tempo do sistema. Destinos bitemporais requerem ambos. Os seguintes snippets mostram apenas a definição do fluxo. Para obter o código completo do pipeline, consulte Exemplo: Rastrear cargos de funcionários com AUTO CDC bitemporal.
- 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;
Para as colunas que os destinos bitemporais adicionam e para obter uma explicação completa com dados de exemplo, atualizações fora de ordem, correções e query, consulte Bitemporal AUTO CDC.
CDC AUTOMÁTICO DE exemplos de instantâneos
As seções a seguir fornecem exemplos de uso de AUTO CDC FROM SNAPSHOT para processar Snapshot em tabelas de destino SCD Tipo 1 ou Tipo 2. Para obter informações sobre quando usar esta API, consulte captura de dados de alterações (CDC) e Snapshot.
Os exemplos nesta seção incluem implementações em Python e SQL. Para ver a sintaxe SQL completa, consulte CREATE FLOW (pipelines).
Example: Process periodic Snapshot
Use essa abordagem quando um sistema de origem exporta um snapshot completo em uma programação regular, como um arquivo por hora, e os snapshots chegam em ordem. Neste exemplo, cada snapshot é um arquivo CSV cujo nome inclui a data e hora da exportação, como users_2026-10-15-09.csv.
- A implementação SQL usa uma query
WITH VERSIONpara localizar o próximo arquivo de snapshot e usa a data e a hora no nome do arquivo como a versão do snapshot. O pipeline rastreia a última versão processada. - A implementação Python usa uma função de versão para encontrar o próximo arquivo de snapshot e usa a data e a hora no nome do arquivo como a versão do snapshot.
Você também pode ler snapshots de outros tipos de origem, como uma tabela em Python ou SQL, ou uma conexão JDBC em Python. Consulte Inicializar um destino vazio a partir de um snapshot.
O passo 1: Criar arquivos de snapshot de exemplo
Crie um volume e escreva dois arquivos de snapshot por hora nele. Faça a execução do seguinte código de um notebook na pasta explorations do seu 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
)
o passo 2: execução AUTO CDC FROM Snapshot
Você precisa de um pipeline para executar o código nesta etapa. Consulte Develop and debug ETL pipelines with the Lakeflow Pipelines Editor.
Em um pipeline, crie um novo arquivo Python ou SQL na pasta transformations, adicione o seguinte código e faça a execução do 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;
Execução o pipeline. Durante a atualização, o fluxo processa o snapshot das 09:00 seguido pelo snapshot das 10:00. AUTO CDC FROM SNAPSHOT compara os dois snapshots e detecta que o usuário 1 foi excluído, os usuários 2 e 3 foram atualizados e os usuários 4 e 6 foram inseridos. As versões de snapshot analisadas dos nomes de arquivo são armazenadas nas colunas __START_AT e __END_AT.
Com o SCD Tipo 2, a tabela de destino contém os seguintes registros:
userId | city | __START_AT | __END_AT |
|---|---|---|---|
1 | Oaxaca | 15/10/2026-09 | 15/10/2026-10 |
2 | Monterrey | 15/10/2026-09 | 15/10/2026-10 |
2 | Carmelo | 15/10/2026-10 | null |
3 | Tijuana | 15/10/2026-09 | 15/10/2026-10 |
3 | Los Angeles | 15/10/2026-10 | null |
4 | Vale da Morte | 15/10/2026-10 | null |
6 | Kings Canyon | 15/10/2026-10 | null |
O usuário 1 foi encerrado (excluído). Os usuários 2 e 3 têm duas versões cada, mostrando as alterações em suas cidades. Os usuários 4 e 6 foram inseridos recentemente.
Para usar o SCD tipo 1 em vez do SCD tipo 2, defina stored_as_scd_type=1 em Python ou STORED AS SCD TYPE 1 em SQL. A tabela de destino SCD tipo 1 não inclui as colunas __START_AT e __END_AT.
Com SCD Tipo 1, a tabela de destino mostra apenas o estado atual:
userId | city |
|---|---|
2 | Carmelo |
3 | Los Angeles |
4 | Vale da Morte |
6 | Kings Canyon |
o passo 3: Simule um novo Snapshot e execute novamente
Escreva outro arquivo de snapshot por hora para simular a chegada de um novo export. Execute esse código de um notebook na pasta explorations de seu 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
)
Execução o pipeline novamente. O fluxo seleciona apenas o snapshot das 11:00 porque as versões anteriores já foram processadas. O usuário 3 é atualizado, o usuário 7 é inserido e os outros registros não são alterados.
Se vários arquivos por hora chegarem entre as atualizações do pipeline, ambas as implementações processam cada arquivo disponível na ordem da versão durante a próxima atualização.
Exemplo: Inicializar um destino vazio de um snapshot
Use esta abordagem para inicializar um destino novo e vazio a partir de um snapshot autoritativo. Defina once=True em Python ou use a palavra-chave ONCE em SQL para tornar esse um fluxo de uma única vez. Após o commit do fluxo ser bem-sucedido, as atualizações incrementais subsequentes do pipeline ignoram esse fluxo. Um refresh completo limpa o destino e faz a execução do fluxo novamente.
Este exemplo usa uma tabela como fonte de snapshot e armazena o estado atual com SCD Tipo 1. Para adicionar um snapshot a um destino que também recebe eventos de um fluxo AUTO CDC, consulte Adicionar um backfill a uma tabela AUTO CDC SCD Tipo 1.
o passo 1: Criar o Snapshot de origem
Crie uma tabela que contenha o estado atual completo da fonte:
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');
O passo 2: Criar o fluxo de snapshot único
Em um pipeline, crie um arquivo Python ou SQL na pasta transformations, adicione o seguinte código e execute a execução do pipeline. Consulte Desenvolver e depurar pipelines ETL com o editor do 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;
Usar uma fonte JDBC em Python
Para inicializar o destino a partir de uma conexão JDBC no compute clássico, defina uma view que lê a tabela de origem e use o nome da view como o argumento 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()
)
Defina source = "initial_users" e once = True ao criar o fluxo.
Após a conclusão da atualização, o alvo contém as seguintes linhas:
userId | city |
|---|---|
1 | Oaxaca |
2 | Monterrey |
3 | Tijuana |
O passo 3: Verificar o comportamento do fluxo único
Substitua os dados de origem por um snapshot diferente:
TRUNCATE TABLE main.cdc_tutorial.initial_users;
INSERT INTO main.cdc_tutorial.initial_users VALUES
(2, 'Carmel'),
(3, 'Los Angeles'),
(4, 'Death Valley');
Execução outra atualização incremental do pipeline. O destino permanece inalterado porque o fluxo único já foi concluído. Se você realizar uma execução de refresh completo, o pipeline limpa o destino e executa o fluxo novamente. O destino então contém o snapshot de substituição.
Limitações
- A coluna de sequenciamento deve ser de um tipo de dados classificável. Os valores de sequenciamento
NULLnão são suportados. - Para transmitir dados do destino de um processo AUTO CDC , leia o feed de alterações. Para obter detalhes, consulte Ler um feed de dados de alterações de uma tabela de destino AUTO CDC.
- Os destinos bitemporais têm as seguintes limitações:
AUTO CDC FROM SNAPSHOTnão é compatível. Para processar snapshots, derive um feed de alterações deles primeiro. Consulte Processar snapshots com AUTO CDC bitemporal.- Os fluxos combinados
AUTO CDC FROM SNAPSHOTeAUTO CDCnão são compatíveis. - Fluxos
AUTO CDCmúltiplos que escrevem no mesmo destino bitemporal não são suportados. TRACK HISTORY ON(track_history_column_listetrack_history_except_column_listem Python) não é compatível. Destinos bitemporais rastreiam a história para cada coluna.COLUMNS TO UPDATEeIGNORE NULL UPDATESnão são compatíveis.APPLY AS TRUNCATE WHENnão é suportado.
Recurso adicional
- captura de dados de alterações (CDC) e Snapshot: Aprenda sobre conceitos CDC , Snapshot e tipos SCD .
- Replicar uma tabela RDBMS externa usando
AUTO CDC: Aprenda como realizar a hidratação inicial com um fluxooncee, em seguida, continuar o processamento de alterações. - Backfilling data histórica with pipelines: Learn how to backfill append-only and AUTO CDC SCD Type 1 targets.
- AUTO CDC Bitemporal: Aprenda como rastrear a história ao longo do tempo comercial e tempo do sistema.
- Tópicos avançados do AUTO CDC: Aprenda sobre operações de alteração em destinos do AUTO CDC, leitura de feeds de dados de alteração e processamento de métricas.
- Rebobinar e reexecutar um pipeline: saiba como restaurar um destino do AUTO CDC para um ponto anterior no tempo e reprocessar as alterações.
- tutorial: Construa um pipeline ETL usando captura de dados de alterações (CDC)