Eventi e flussi di dati

Panoramica

La gerarchia dei dati in Datastream è:

  • Uno stream, composto da un'origine dati e una destinazione.
  • Un oggetto, ovvero una parte di un flusso, ad esempio una tabella di un database specifico.
  • Un evento, cioè una singola modifica generata da un oggetto specifico, ad esempio un inserimento di database.

A stream, oggetti ed eventi sono associati dati e metadati. Questi dati e metadati possono essere utilizzati per scopi diversi.

Informazioni sugli eventi

Ogni evento è costituito da tre tipi di dati:

  • Dati sugli eventi:rappresentano la modifica ai dati stessi provenienti dall'oggetto proveniente dall'origine del flusso. Ogni evento contiene la totalità della riga che è stata modificata.
  • Metadati generici:questi metadati vengono visualizzati su ogni evento generato da Datastream e utilizzato per azioni come la rimozione dei dati duplicati nella destinazione.
  • Metadati specifici della sorgente:questi metadati vengono visualizzati su ogni evento generato da una specifica origine dello stream. Questi metadati variano in base alla fonte.

Dati sull'evento

I dati sugli eventi sono il payload di ogni modifica da un determinato oggetto proveniente da un'origine del flusso.

Gli eventi sono in formato Avro o JSON.

Quando lavori con il formato Avro, per ogni colonna l'evento contiene l'indice e il valore della colonna. Utilizzando l'indice della colonna, è possibile recuperare il nome e il tipo unificato della colonna dallo schema nell'intestazione Avro.

Quando utilizzi il formato JSON, per ogni colonna l'evento conterrà il nome e il valore della colonna.

I metadati sugli eventi possono essere utilizzati per raccogliere informazioni sull'origine dell'evento, nonché per rimuovere i dati duplicati nella destinazione e ordinare gli eventi da parte del consumatore a valle.

Le seguenti tabelle elencano e descrivono i campi e i tipi di dati per i metadati degli eventi generici e specifici dell'origine.

Metadati generici

Questi metadati sono coerenti in tutti gli stream di tutti i tipi.

Campo Tipo di Avro Tipo JSON Descrizione
stream_name string string Il nome univoco dello stream definito al momento della creazione.
read_method string string

Indica se i dati sono stati letti dall'origine utilizzando un metodo Change Data Capture (CDC), come parte del backfill storico o di un'attività di integrazione creata quando viene eseguito il rollback di una transazione durante la replica CDC.

I valori possono essere:

  • oracle-cdc-logminer
  • oracle-backfill
  • oracle-supplementation
  • mysql-cdc-binlog
  • mysql-backfill-incremental
  • mysql-backfill-fulldump
  • postgres-cdc-wal
  • postgresql-backfill
object string string Il nome utilizzato per raggruppare diversi tipi di eventi, in genere il nome della tabella o dell'oggetto nell'origine.
schema_key string string L'identificatore univoco dello schema unificato dell'evento.
uuid string string Un identificatore univoco per l'evento generato da Datastream.
read_timestamp timestamp-milli string Il timestamp (UTC) in cui il record è stato letto da Datastream (il timestamp dell'epoca in millisecondi).
source_timestamp timestamp-milli string Il timestamp (UTC) in cui il record è stato modificato nell'origine (il timestamp dell'epoca in millisecondi).
sort_keys {"type": "array", "items": ["string", "long"]} array Un array di valori che può essere utilizzato per ordinare gli eventi nell'ordine in cui si sono verificati.

Metadati specifici dell'origine

Questi metadati sono associati agli eventi CDC e di backfill da un database di origine. Per visualizzare questi metadati, seleziona una fonte dal menu a discesa in basso.

Origine Campo Tipo di Avro Tipo JSON Descrizione
MySQL log_file string string Il file di log da cui Datastream estrae gli eventi nella replica CDC.
MySQL log_position lunghi lunghi La posizione del log (offset) nel log binario MySQL.
MySQL primary_keys array di stringhe array di stringhe L'elenco di (uno o più) nomi di colonna che compongono la chiave primaria delle tabelle. Se la tabella non ha una chiave primaria, il campo è vuoto.
MySQL is_deleted boolean boolean
  • Un valore true indica che la riga è stata eliminata nell'origine.
  • Un valore false indica che la riga non è stata eliminata.
MySQL database string string Il database associato all'evento.
MySQL table string string La tabella associata all'evento.
MySQL change_type string string

Il tipo di modifica (INSERT, UPDATE-INSERT, UPDATE-DELETE e DELETE) rappresentato dall'evento.

Oracle log_file string string Il file di log da cui Datastream estrae gli eventi nella replica CDC.
Oracle scn lunghi lunghi La posizione del log (offset) nel log delle transazioni Oracle.
Oracle row_id string string row_id di Oracle.
Oracle is_deleted boolean boolean
  • Un valore true indica che la riga è stata eliminata nell'origine.
  • Un valore false indica che la riga non è stata eliminata.
Oracle database string string Il database associato all'evento.
Oracle schema string string Lo schema associato alla tabella dell'evento.
Oracle table string string La tabella associata all'evento.
Oracle change_type string string

Il tipo di modifica (INSERT, UPDATE-INSERT, UPDATE-DELETE e DELETE) rappresentato dall'evento.

Oracle tx_id string string L'ID transazione a cui appartiene l'evento.
Oracle rs_id string string L'ID del set di record. L'accoppiamento di rs_id e ssn identifica in modo univoco una riga in V$LOGMNR_CONTENTS. rs_id identifica in modo univoco il record di ripetizione che ha generato la riga.
Oracle ssn lunghi lunghi Un numero di sequenza SQL. Questo numero viene utilizzato con rs_id e identifica in modo univoco una riga in V$LOGMNR_CONTENTS.
PostgreSQL schema string string Lo schema associato alla tabella dell'evento.
PostgreSQL table string string La tabella associata all'evento.
PostgreSQL is_deleted boolean boolean
  • Un valore true indica che la riga è stata eliminata nell'origine.
  • Un valore false indica che la riga non è stata eliminata.
PostgreSQL change_type string string Il tipo di modifica (INSERT, UPDATE, DELETE) rappresentato dall'evento.
PostgreSQL tx_id string string L'ID transazione a cui appartiene l'evento.
PostgreSQL lsn string string Il numero della sequenza di log per la voce corrente.
PostgreSQL primary_keys array di stringhe array di stringhe L'elenco di (uno o più) nomi di colonna che compongono la chiave primaria delle tabelle. Se la tabella non ha una chiave primaria, il campo è vuoto.
SQL Server table string string La tabella associata all'evento.
SQL Server database lunghi lunghi Il database associato all'evento.
SQL Server schema array di stringhe array di stringhe Lo schema associato alla tabella dell'evento.
SQL Server is_deleted boolean boolean
  • Un valore true indica che la riga è stata eliminata nell'origine.
  • Un valore falso indica che la riga non è stata eliminata.
SQL Server lsn string string Il numero di sequenza di log per l'evento.
SQL Server tx_id string string L'ID transazione a cui appartiene l'evento.
SQL Server physical_location Array numero intero Array numero intero La posizione fisica del record di log descritta da tre numeri interi: ID file, ID pagina e ID slot del record.
SQL Server replication_index Array di stringhe Array di stringhe L'elenco dei nomi di colonna di un indice che può identificare in modo univoco una riga della tabella.
SQL Server change_type String String

Il tipo di modifica ("INSERT", UPDATE, "DELETE") rappresentato dall'evento.

Esempio di flusso di eventi

Questo flusso illustra gli eventi generati da tre operazioni consecutive: INSERT, UPDATE e DELETE, su una singola riga in una tabella SAMPLE per un database di origine.

TEMPO THIS_IS_MY_PK (int) FIELD1 (nchar nullable) FIELD2 (nchar non-null)>
0 1231535353 foo TLV
1 1231535353 NULLA TLV

INSERISCI (T0)

Il payload del messaggio è costituito dall'intera nuova riga.

{
  "stream_name": "projects/myProj/locations/myLoc/streams/Oracle-to-Source",
  "read_method": "oracle-cdc-logminer",
  "object": "SAMPLE.TBL",
  "uuid": "d7989206-380f-0e81-8056-240501101100",
  "read_timestamp": "2019-11-07T07:37:16.808Z",
  "source_timestamp": "2019-11-07T02:15:39",  
  "source_metadata": {
    "log_file": ""
    "scn": 15869116216871,
    "row_id": "AAAPwRAALAAMzMBABD",
    "is_deleted": false,
    "database": "DB1",
    "schema": "ROOT",
    "table": "SAMPLE"
    "change_type": "INSERT",
    "tx_id": 
    "rs_id": "0x0073c9.000a4e4c.01d0",
    "ssn": 67,
  },
  "payload": {
    "THIS_IS_MY_PK": "1231535353",
    "FIELD1": "foo",
    "FIELD2": "TLV",
  }
}

AGGIORNAMENTO (T1)

Il payload del messaggio è costituito dall'intera nuova riga. Non include valori precedenti.

{
  "stream_name": "projects/myProj/locations/myLoc/streams/Oracle-to-Source",
  "read_method": "oracle-cdc-logminer",
  "object": "SAMPLE.TBL",
  "uuid": "e6067366-1efc-0a10-a084-0d8701101101",
  "read_timestamp": "2019-11-07T07:37:18.808Z",
  "source_timestamp": "2019-11-07T02:17:39",  
  "source_metadata": {
    "log_file": 
    "scn": 15869150473224,
    "row_id": "AAAGYPAATAAPIC5AAB",
    "is_deleted": false,
    "database":
    "schema": "ROOT",
    "table": "SAMPLE"
    "change_type": "UPDATE",
    "tx_id":
    "rs_id": "0x006cf4.00056b26.0010",
    "ssn": 0,
  },
  "payload": {
    "THIS_IS_MY_PK": "1231535353",
    "FIELD1": null,
    "FIELD2": "TLV",
  }
}

ELIMINA (T2)

Il payload del messaggio è costituito dall'intera nuova riga.

{
  "stream_name": "projects/myProj/locations/myLoc/streams/Oracle-to-Source",
  "read_method": "oracle-cdc-logminer",
  "object": "SAMPLE.TBL",
  "uuid": "c504f4bc-0ffc-4a1a-84df-6aba382fa651",
  "read_timestamp": "2019-11-07T07:37:20.808Z",
  "source_timestamp": "2019-11-07T02:19:39",
  "source_metadata": {
    "log_file": 
    "scn": 158691504732555,
    "row_id": "AAAGYPAATAAPIC5AAC",
    "is_deleted": true,
    "database":
    "schema": "ROOT",
    "table": "SAMPLE"
    "change_type": "DELETE",
    "tx_id":
    "rs_id": "0x006cf4.00056b26.0011",
    "ssn": 0,
  },
  "payload": {
    "THIS_IS_MY_PK": "1231535353",
    "FIELD1": null,
    "FIELD2": "TLV",
  }
}

Ordine e coerenza

Questa sezione illustra in che modo Datastream gestisce l'ordinamento e la coerenza.

Ordine

Datastream non garantisce l'ordinamento, ma ogni evento contiene l'intera riga di dati e il timestamp relativo alla scrittura dei dati nell'origine. In BigQuery, gli eventi non in ordine verranno uniti automaticamente nella sequenza corretta. BigQuery utilizza i metadati degli eventi e un numero di sequenza di modifica interno (CSN) per applicare gli eventi alla tabella nell'ordine corretto. In Cloud Storage, gli eventi dello stesso periodo possono riguardare più di un file.

Gli eventi generati nell'ordine sbagliato avvengono per impostazione predefinita quando viene eseguito il backfill degli eventi per il backfill iniziale dei dati creato all'avvio del flusso.

L'ordinamento può essere dedotto da origine per origine.

Origine Descrizione
MySQL

Gli eventi che fanno parte del backfill iniziale hanno il campo read_method che inizia con mysql-backfill. Non ha alcuna implicazioni nell'ordine in cui gli eventi vengono ricevuti nel backfill perché possono essere utilizzati in qualsiasi ordine.

Il campo read_method degli eventi che fanno parte della replica in corso è impostato su mysql-cdc-binlog.

L'ordine può essere dedotto dalla combinazione dei campi log_file e del campo log_position con offset rispetto al file di log. Questa combinazione fornisce un numero univoco e in modo incrementale che identifica l'ordine di operazione nel database.

Oracle

Gli eventi che fanno parte del backfill iniziale hanno il campo read_method che inizia con oracle-backfill. Non ha alcuna implicazioni nell'ordine in cui gli eventi vengono ricevuti nel backfill perché possono essere utilizzati in qualsiasi ordine.

Il campo read_method degli eventi che fanno parte della replica in corso è impostato su oracle-cdc-logminer.

L'ordine può essere dedotto dalla combinazione del campo rs_id (ID del set di record) e del campo ssn (un numero di sequenza SQL). Questa combinazione fornisce un numero univoco e in modo incrementale che identifica l'ordine di operazione nel database.

PostgreSQL

Gli eventi che fanno parte del backfill iniziale hanno il campo read_method che inizia con postgresql-backfill. Non ha alcuna implicazioni nell'ordine in cui gli eventi vengono ricevuti nel backfill perché possono essere utilizzati in qualsiasi ordine.

Il campo read_method degli eventi che fanno parte della replica in corso è impostato su postgres-cdc-wal.

L'ordine può essere dedotto dalla combinazione dei campi source_timestamp e lsn (numero di sequenza del log). Questa combinazione fornisce un numero univoco e in modo incrementale che identifica l'ordine di operazione nel database.

SQL Server

Gli eventi che fanno parte del backfill iniziale hanno il campo read_method che inizia con sqlserver-backfill. Non ha alcuna implicazioni nell'ordine in cui gli eventi vengono ricevuti nel backfill perché possono essere utilizzati in qualsiasi ordine.

Il campo read_method degli eventi che fanno parte della replica in corso è impostato su sqlserver-cdc.

L'ordine può essere dedotto dalla combinazione dei campi source_timestamp e lsn (numero di sequenza del log). Questa combinazione fornisce un numero univoco e in modo incrementale che identifica l'ordine di operazione nel database.

Coerenza

Datastream garantisce che i dati del database di origine verranno inviati alla destinazione almeno una volta. Non verrà perso nessun evento, ma c'è la possibilità che lo stream contenga eventi duplicati. La finestra degli eventi duplicati deve avere una durata dell'ordine dei minuti ed è possibile utilizzare l'identificatore univoco universale (UUID) dell'evento nei metadati dell'evento per rilevare i duplicati.

Quando i file di log del database contengono transazioni non impegnate, se viene eseguito il rollback di alcune transazioni, il database riflette nei file di log come operazioni DML (Data Manipulation Language) "inverse". Ad esempio, un'operazione di rollback di INSERT avrà un'operazione DELETE corrispondente. Datastream legge queste operazioni dai file di log.

Informazioni sugli stream

Ogni stream include metadati che descrivono sia lo stream sia l'origine da cui estrae i dati. Questi metadati includono informazioni come il nome dello stream, i profili di connessione di origine e di destinazione e così via.

Per visualizzare la definizione completa dell'oggetto Stream, consulta la documentazione di riferimento API.

Stato e stato dello stream

Uno stream può avere uno dei seguenti stati:

  • Not started
  • Starting
  • Running
  • Draining
  • Paused
  • Failed
  • Failed permanently

Puoi utilizzare i log per trovare ulteriori informazioni sullo stato, ad esempio il backfill delle tabelle, il numero di righe elaborate e così via. Puoi anche utilizzare l'API FetchStreamErrors per recuperare gli errori.

Metadati degli oggetti disponibili utilizzando l'API Discover

L'API Discover restituisce gli oggetti che rappresentano la struttura degli oggetti definiti nell'origine dati o nella destinazione rappresentata dal profilo di connessione. Ogni oggetto include metadati relativi all'oggetto stesso e a ogni campo di dati che estrae. Questi metadati sono disponibili tramite l'API discovery.