API:erna för AUTO CDC: Förenkla insamlingen av ändringsdata med Lakeflow deklarativa pipelines

Deklarativa pipelines för Lakeflow förenklar ändringsdatainsamling (CDC) med API:erna AUTO CDC och AUTO CDC FROM SNAPSHOT.

Vilket gränssnitt du använder beror på källan för ändringsdata:

• Använd AUTO CDC för att bearbeta ändringar från ett ändringsdataflöde (CDF).
• Använd AUTO CDC FROM SNAPSHOT (offentlig förhandsversion och endast tillgänglig för Python) för att bearbeta ändringar i databasögonblicksbilder.

Tidigare användes instruktionen MERGE INTO ofta för bearbetning av CDC-poster på Azure Databricks. Kan dock MERGE INTO ge felaktiga resultat på grund av poster som inte är sekvenserade eller kräver komplex logik för att ordna om poster.

API:et AUTO CDC stöds i SQL- och Python-gränssnitten för "Lakeflow Declarative Pipelines". API:n AUTO CDC FROM SNAPSHOT stöds i Lakeflow Deklarativa Pipelines Python-gränssnittet.

Både AUTO CDC och AUTO CDC FROM SNAPSHOT stöder uppdatering av tabeller med SCD typ 1 och typ 2:

• Använd SCD typ 1 för att uppdatera poster direkt. Historik behålls inte för uppdaterade register.
• Använd SCD typ 2 för att behålla en historik över poster, antingen på alla uppdateringar eller vid uppdateringar av en angiven uppsättning kolumner.

Syntax och andra referenser finns i AUTO CDC for Lakeflow Declarative Pipelines SQL, AUTO CDC for Lakeflow Declarative Pipelines Python och AUTO CDC FROM SNAPSHOT for Lakeflow Declarative Pipelines Python.

Kravspecifikation

Om du vill använda CDC-API:erna måste din pipeline konfigureras för att använda serverlösa Lakeflow deklarativa pipelines eller Lakeflow deklarativa pipelines Pro eller Advancededitioner.

Hur implementeras CDC med API:et FÖR AUTOMATISK CDC?

Genom att behandla osynkrona poster automatiskt säkerställer AUTO CDC API i Lakeflow Deklarativa Pipelines korrekt bearbetning av CDC-poster och eliminerar behovet av att utveckla komplex logik för att hantera osynkrona poster. Du måste ange en kolumn i källdata för att sekvensera poster, vilket Lakeflow Deklarativa Pipelines tolkar som en representation av en enhetligt ökande ordning på källdata. Lakeflow Deklarativa pipelines hanterar automatiskt data som anländer ur ordning. För SCD typ 2-ändringar överför Lakeflow deklarativa pipelines lämpliga sekvenseringsvärden till måltabellens __START_AT och __END_AT kolumner. Det bör finnas en distinkt uppdatering per nyckel vid varje sekvenseringsvärde och NULL-sekvenseringsvärden stöds inte.

Om du vill utföra CDC-bearbetning med AUTO CDCskapar du först en strömningstabell och använder sedan -instruktionen AUTO CDC ... INTOcreate_auto_cdc_flow() i SQL eller funktionen i Python för att ange källa, nycklar och sekvensering för ändringsflödet. För att skapa måluppspelningstabellen, använd CREATE OR REFRESH STREAMING TABLE-instruktionen i SQL eller create_streaming_table()-funktionen i Python. Se exempel på SCD-typ 1 och typ 2-bearbetning .

Syntaxinformation finns i SQL-referensen för Lakeflow Deklarativa pipelines eller Python-referensen.

Hur implementeras CDC med API:et AUTO CDC FROM SNAPSHOT ?

AUTO CDC FROM SNAPSHOT är ett deklarativt API som effektivt avgör ändringar i källdata genom att jämföra en serie ögonblicksbilder i ordning och sedan köra bearbetningen som krävs för CDC-bearbetning av posterna i ögonblicksbilderna. AUTO CDC FROM SNAPSHOT stöds endast av Lakeflow Declarative Pipelines Python-gränssnitt.

AUTO CDC FROM SNAPSHOT stöder inmatning av ögonblicksbilder från flera källtyper:

• Använd periodisk inmatning av ögonblicksbilder för att mata in ögonblicksbilder från en befintlig tabell eller vy. AUTO CDC FROM SNAPSHOT har ett enkelt, strömlinjeformat gränssnitt som stöder regelbunden inmatning av ögonblicksbilder från ett befintligt databasobjekt. En ny ögonblicksbild matas in med varje pipelineuppdatering och inmatningstiden används som ögonblicksbildversion. När en pipeline körs i kontinuerligt läge matas flera ögonblicksbilder in med varje pipelineuppdatering under en period som bestäms av inställningen för utlösarintervall för flödet som innehåller bearbetningen AUTO CDC FROM SNAPSHOT .
• Använd historisk inmatning av ögonblicksbilder för att bearbeta filer som innehåller ögonblicksbilder av databasen, till exempel ögonblicksbilder som genererats från en Oracle- eller MySQL-databas eller ett informationslager.

Om du vill utföra CDC-bearbetning från valfri källtyp med AUTO CDC FROM SNAPSHOTskapar du först en strömmande tabell och använder create_auto_cdc_from_snapshot_flow() sedan funktionen i Python för att ange ögonblicksbilden, nycklarna och andra argument som krävs för att implementera bearbetningen. Se exemplen på periodisk inmatning av ögonblicksbilder och historisk inmatning av ögonblicksbilder .

Ögonblicksbilderna som skickas till API:et måste vara i stigande ordning efter version. Om Lakeflow Deklarativa Pipelines identifierar en ögonblicksbild som är utom ordning, påträffas ett fel.

Syntaxinformation finns i Python-referensen för Lakeflow deklarativa pipelines.

Använda flera kolumner för sekvensering

Du kan sekvensera med flera kolumner (till exempel en tidsstämpel och ett ID för att bryta lika resultat), du kan använda en STRUCT för att kombinera dem: det sorterar först efter det första fältet i STRUCT och i händelse av lika resultat beaktas det andra fältet och så vidare.

Exempel i SQL:

SEQUENCE BY STRUCT(timestamp_col, id_col)

Exempel i Python:

sequence_by = struct("timestamp_col", "id_col")

Begränsningar

Kolumnen som används för sekvensering måste vara en sorterbar datatyp.

Exempel: SCD-typ 1 och SCD typ 2-bearbetning med CDF-källdata

Följande avsnitt ger exempel på frågor av typ 1 och typ 2 inom SCD för Lakeflow Declarative Pipelines, vilka uppdaterar måltabeller baserat på källhändelser från ett ändringsdataflöde som:

1. Skapar nya användarposter.
2. Tar bort en användarregistrering.
3. Uppdaterar användarregister. I exemplet SCD typ 1 kommer de sista UPDATE åtgärderna in sent och tas bort från måltabellen, vilket demonstrerar hanteringen av händelser utanför ordningen.

I följande exempel förutsätter vi att du är bekant med att konfigurera och uppdatera deklarativa Lakeflow-pipelines. Se Självstudie: Skapa en ETL-pipeline med ändringsdatafångst med Lakeflows deklarativa pipelines.

Om du vill köra de här exemplen måste du börja med att skapa en exempeldatauppsättning. Se Generera testdata.

Följande är indataposterna för dessa exempel:

Om du avkommenterar den sista raden i exempeldata infogas följande post som anger var poster ska trunkeras:

Bearbeta SCD-typ 1-uppdateringar

I följande exempel visas bearbetning av SCD typ 1-uppdateringar:

python

from pyspark import pipelines as dp
from pyspark.sql.functions import col, expr

@dp.view
def users():
  return spark.readStream.table("cdc_data.users")

dp.create_streaming_table("target")

dp.create_auto_cdc_flow(
  target = "target",
  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 and populate the target table.
CREATE OR REFRESH STREAMING TABLE target;

CREATE FLOW flowname AS AUTO CDC INTO
  target
FROM
  stream(cdc_data.users)
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;

När du har kört SCD typ 1-exemplet innehåller måltabellen följande poster:

När du har kört SCD typ 1-exemplet med den ytterligare TRUNCATE posten, beskäres poster 124 och 126 på grund av TRUNCATE åtgärden vid sequenceNum=3, och då innehåller måltabellen följande post:

Bearbeta SCD-typ 2-uppdateringar

I följande exempel visas bearbetning av SCD typ 2-uppdateringar:

python

from pyspark import pipelines as dp
from pyspark.sql.functions import col, expr

@dp.view
def users():
  return spark.readStream.table("cdc_data.users")

dp.create_streaming_table("target")

dp.create_auto_cdc_flow(
  target = "target",
  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 and populate the target table.
CREATE OR REFRESH STREAMING TABLE target;

CREATE FLOW target_flow
AS AUTO CDC INTO
  target
FROM
  stream(cdc_data.users)
KEYS
  (userId)
APPLY AS DELETE WHEN
  operation = "DELETE"
SEQUENCE BY
  sequenceNum
COLUMNS * EXCEPT
  (operation, sequenceNum)
STORED AS
  SCD TYPE 2;

Efter att ha kört SCD typ 2-exemplet innehåller måltabellen följande poster:

En SCD-typ 2-fråga kan också ange en delmängd av utdatakolumner som ska spåras för historik i måltabellen. Ändringar i andra kolumner uppdateras på plats istället för att generera nya historikposter. I följande exempel visas hur du city undantar kolumnen från spårning:

I följande exempel visas hur du använder spårningshistorik med SCD-typ 2:

python

from pyspark import pipelines as dp
from pyspark.sql.functions import col, expr

@dp.view
def users():
  return spark.readStream.table("cdc_data.users")

dp.create_streaming_table("target")

dp.create_auto_cdc_flow(
  target = "target",
  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 and populate the target table.
CREATE OR REFRESH STREAMING TABLE target;

CREATE FLOW target_flow
AS AUTO CDC INTO
  target
FROM
  stream(cdc_data.users)
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)

När du har kört det här exemplet utan den ytterligare TRUNCATE posten innehåller måltabellen följande poster:

Generera testdata

Koden nedan tillhandahålls för att generera en exempeldatauppsättning för användning i exempelfrågorna som finns i den här självstudien. Förutsatt att du har rätt autentiseringsuppgifter för att skapa ett nytt schema och skapa en ny tabell kan du köra dessa instruktioner med antingen en notebook-fil eller Databricks SQL. Följande kod är inte avsedd att användas i Lakeflow Deklarativa Pipelines.

CREATE SCHEMA IF NOT EXISTS cdc_data;

CREATE TABLE
  cdc_data.users
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 above batch at sequenceNum 6 will be the final state.
  (125, "Mercedes", "Mexicali",    "UPDATE", 5),
  (123, "Isabel",   "Chihuahua",   "UPDATE", 5)
  -- Uncomment to test TRUNCATE.
  -- ,(null, null,      null,          "TRUNCATE", 3)
);

Exempel: Periodisk bearbetning av ögonblicksbilder

I följande exempel visas SCD-typ 2-bearbetning som matar in ögonblicksbilder av en tabell som lagras på mycatalog.myschema.mytable. Resultatet av bearbetningen skrivs till en tabell med namnet target.

mycatalog.myschema.mytable registerposter med tidsstämpeln 2024-01-01 00:00:00

mycatalog.myschema.mytable registreringar vid tidsstämpeln 2024-01-01 12:00:00

from pyspark import pipelines as dp

@dp.view(name="source")
def source():
 return spark.read.table("mycatalog.myschema.mytable")

dp.create_streaming_table("target")

dp.create_auto_cdc_from_snapshot_flow(
 target="target",
 source="source",
 keys=["key"],
 stored_as_scd_type=2
)

Efter att ha bearbetat snapshotarna innehåller måltabellen följande records:

Exempel: Bearbetning av historiska ögonblicksbilder

I följande exempel visas SCD-typ 2-bearbetning som uppdaterar en måltabell baserat på källhändelser från två ögonblicksbilder som lagras i ett molnlagringssystem:

Ögonblicksbild vid timestamp, lagrad i /<PATH>/filename1.csv

Ögonblicksbild vid timestamp + 5, lagrad i /<PATH>/filename2.csv

I följande kodexempel visas bearbetning av SCD typ 2-uppdateringar med dessa ögonblicksbilder:

from pyspark import pipelines as dp

def exist(file_name):
  # Storage system-dependent function that returns true if file_name exists, false otherwise

# This function returns a tuple, where the first value is a DataFrame containing the snapshot
# records to process, and the second value is the snapshot version representing the logical
# order of the snapshot.
# Returns None if no snapshot exists.
def next_snapshot_and_version(latest_snapshot_version):
  latest_snapshot_version = latest_snapshot_version or 0
  next_version = latest_snapshot_version + 1
  file_name = "dir_path/filename_" + next_version + ".csv"
  if (exist(file_name)):
    return (spark.read.load(file_name), next_version)
   else:
     # No snapshot available
     return None

dp.create_streaming_live_table("target")

dp.create_auto_cdc_from_snapshot_flow(
  target = "target",
  source = next_snapshot_and_version,
  keys = ["Key"],
  stored_as_scd_type = 2,
  track_history_column_list = ["TrackingCol"]
)

Efter att ha bearbetat ögonblicksbilderna innehåller mål-tabellen följande poster:

Lägga till, ändra eller ta bort data i en direktuppspelningstabell

Om din pipeline publicerar tabeller till Unity Catalog kan du använda DML-instruktioner ( datamanipuleringsspråk ), inklusive infognings-, uppdaterings-, borttagnings- och sammanslagningsinstruktioner, för att ändra målströmningstabeller som skapats av AUTO CDC ... INTO -instruktioner.

Eftersom Lakeflow Declarative Pipelines använder den specificerade SEQUENCE BY-kolumnen och sprider lämpliga sekvenseringsvärden till kolumnerna __START_AT och __END_AT i måltabellen (för SCD-typ 2) måste du se till att DML-satser använder giltiga värden för dessa kolumner för att upprätthålla rätt ordning på poster. Se Hur implementeras CDC med API:et FÖR AUTOMATISK CDC?.

Mer information om hur du använder DML-instruktioner med strömmande tabeller finns i Lägga till, ändra eller ta bort data i en strömmande tabell.

I följande exempel infogas en aktiv post med en startsekvens på 5:

INSERT INTO my_streaming_table (id, name, __START_AT, __END_AT) VALUES (123, 'John Doe', 5, NULL);

Läsa ett ändringsdataflöde från en AUTO CDC-måltabell

I Databricks Runtime 15.2 och senare kan du läsa ett ändringsdataflöde från en strömmande tabell som utgör måltavlan för AUTO CDC eller AUTO CDC FROM SNAPSHOT querys på samma sätt som du läser ett ändringsdataflöde från andra Delta-tabeller. Följande krävs för att läsa ändringsdataflödet från en målströmningstabell:

• Målsströmningstabellen måste publiceras till Unity Catalog. Se Använd Unity Catalog med dina deklarativa Lakeflow-pipelines.
• Om du vill läsa ändringsdataflödet från målströmningstabellen måste du använda Databricks Runtime 15.2 eller senare. Om du vill läsa ändringsdataflödet i en annan pipeline måste pipelinen konfigureras för att använda Databricks Runtime 15.2 eller senare.

Du läser ändringsdataflödet från en målströmningstabell som skapades i Lakeflow Deklarativa pipelines på samma sätt som när du läste ett ändringsdataflöde från andra Delta-tabeller. Mer information om hur du använder funktionen Delta-ändringsdataflöde, inklusive exempel i Python och SQL, finns i Använd Delta Lake-ändringsdataflöde i Azure Databricks.

Hämta data om bearbetade poster från en CDC-fråga i Deklarativa pipelines för Lakeflow.

Följande mått samlas in av AUTO CDC frågor:

• num_upserted_rows: Antalet utdatarader som har infogats till datamängden under en uppdatering.
• num_deleted_rows: Antalet befintliga utdatarader som tagits bort från datauppsättningen under en uppdatering.

Måttet num_output_rows, som är utdata för icke-CDC-flöden, samlas inte in för AUTO CDC sökfrågor.

Vilka dataobjekt används för bearbetning av CDC i Lakeflow Deklarativa Pipelines?

När du deklarerar måltabellen i Hive-metaarkivet skapas två datastrukturer:

• En vy med det namn som tilldelats måltabellen.
• En intern bakgrundstabell som används av Lakeflow Deklarativa Pipelines för att hantera CDC-bearbetning. Den här tabellen namnges genom att lägga till __apply_changes_storage_ framför måltabellens namn.

Om du till exempel deklarerar en måltabell med namnet dp_cdc_targetvisas en vy med namnet dp_cdc_target och en tabell med namnet __apply_changes_storage_dp_cdc_target i metaarkivet. Genom att skapa en vy kan Lakeflow Deklarativa Pipelines filtrera bort den extra informationen (till exempel tombstones och versioner) som krävs för att hantera oordnade data. För att visa de bearbetade uppgifterna, använd mål-vy. Eftersom schemat för __apply_changes_storage_ tabellen kan ändras för att stödja framtida funktioner eller förbättringar bör du inte fråga tabellen om produktionsanvändning. Om du lägger till data manuellt i tabellen antas posterna komma före andra ändringar eftersom versionskolumnerna saknas.

Ytterligare resurser

• Självstudie: Skapa en ETL-pipeline med ändringsdatafångst med Lakeflow Deklarativa Pipelines