Eventi e flussi di dati

Panoramica

La gerarchia dei dati in Datastream è la seguente:

• Uno stream, composto da un'origine dati e una destinazione.
• Un oggetto, ovvero una parte di uno stream, 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.

Flussi, oggetti ed eventi sono associati a 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:rappresenta la modifica ai dati stessi dall'oggetto proveniente dall'origine dello stream. Ogni evento contiene l'intera riga modificata.
• Metadati generici: questi metadati vengono visualizzati su ogni evento generato da Datastream utilizzato per azioni, come la rimozione di dati duplicati nella destinazione.
• Metadati specifici dell'origine: questi metadati vengono visualizzati in ogni evento generato da un'origine stream specifica. Questi metadati variano a seconda della fonte.

Dati sull'evento

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

Gli eventi sono in formato Avro o JSON.

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

Nota: quando Datastream converte i dati nel formato Avro, i caratteri speciali nei nomi delle colonne vengono sostituiti con trattini bassi. Ciò può portare a nomi di colonne duplicati e causare l'errore degli stream. Per ulteriori informazioni sulle convenzioni di denominazione in Avro, consulta la documentazione di Apache Avro.

Quando lavori con il formato JSON, l'evento conterrà il nome e il valore di ogni colonna per ogni colonna.

I metadati degli eventi possono essere utilizzati per raccogliere informazioni sull'origine dell'evento, nonché per rimuovere i dati duplicati nella destinazione e ordinare gli eventi dal 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 CDC (Change Data Capture), come parte del backfill storico o come parte di un'attività di integrazione creata quando viene eseguito il rollback di una transazione durante la replica CDC. I valori possibili sono: 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-millis	string	Il timestamp (UTC) in cui il record è stato letto da Datastream (il timestamp epoch in millisecondi).
source_timestamp	timestamp-millis	string	Il timestamp (UTC) quando il record è stato modificato nell'origine (il timestamp dell'epoca in millisecondi).
sort_keys	{"type": "array", "items": ["string", "long"]}	matrice	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 a eventi CDC e backfill da un database di origine. Per visualizzare questi metadati, seleziona una fonte dal menu a discesa in basso.

Tutte le fonti MySQL Oracle PostgreSQL SQL Server

Origine	Campo	Tipo di Avro	Tipo JSON	Descrizione
MySQL	log_file	string	string	Il file log da cui Datastream estrae gli eventi nella replica CDC.
MySQL	log_position	Lungo	Lungo	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 colonne che compongono la chiave primaria delle tabelle. Se la tabella non ha una chiave primaria, questo campo è vuoto.
MySQL	is_deleted	boolean	boolean	Un valore true indica che la riga è stata eliminata nell'origine. Il 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. Per la replica basata su riga di MySQL, ogni evento per una riga con una modifica della chiave primaria contiene due immagini: un'immagine "prima" con le colonne a cui viene eseguita la ricerca della riga da aggiornare e un'immagine "dopo" contenente le modifiche. Ad esempio, per la modifica UPDATE-DELETE, UPDATE-DELETE è l'immagine "prima" e UPDATE-INSERT è l'immagine "dopo". Scopri di più sulla replica basata su righe MySQL.
Oracle	log_file	string	string	Il file log da cui Datastream estrae gli eventi nella replica CDC.
Oracle	scn	Lungo	Lungo	La posizione del log (offset) nel log delle transazioni di 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. Il 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 dall'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) rappresentata dall'evento. Per la replica basata su riga Oracle, ogni evento per una riga con una modifica della chiave primaria contiene due immagini: una immagine le cui colonne vengono confrontate con la ricerca della riga da aggiornare, mentre il messaggio "dopo" immagine contenente le modifiche. Ad esempio, per la modifica UPDATE-DELETE, UPDATE-DELETE è il "prima" immagine e UPDATE-INSERT è il "dopo" dell'immagine. Scopri di più sulla replica basata su righe Oracle.
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	Lungo	Lungo	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 dall'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. Il valore false indica che la riga non è stata eliminata.
PostgreSQL	change_type	string	string	Il tipo di modifica (INSERT, UPDATE, DELETE) rappresentata dall'evento. Per la replica basata su riga di PostgreSQL, ogni evento per una riga con una modifica della chiave primaria contiene due immagini: un'immagine "prima" con le colonne a cui viene eseguita la ricerca della riga da aggiornare e un'immagine "dopo" contenente le modifiche. Ad esempio, per la modifica UPDATE-DELETE, UPDATE-DELETE è il "prima" immagine e UPDATE-INSERT è il "dopo" dell'immagine. Scopri di più sulla replica basata su riga di PostgreSQL.
PostgreSQL	tx_id	string	string	L'ID transazione a cui appartiene l'evento.
PostgreSQL	lsn	string	string	Il numero di sequenza del log per la voce corrente.
PostgreSQL	primary_keys	array di stringhe	array di stringhe	L'elenco di (uno o più) nomi di colonne che compongono la chiave primaria delle tabelle. Se la tabella non ha una chiave primaria, questo campo è vuoto.
SQL Server	table	string	string	La tabella associata all'evento.
SQL Server	database	Lungo	Lungo	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 del log per l'evento.
SQL Server	tx_id	string	string	L'ID transazione a cui appartiene l'evento.
SQL Server	physical_location	Array di numeri interi	Array di numeri interi	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 delle colonne di un indice che può identificare in modo univoco una riga nella tabella.
SQL Server	change_type	Stringa	Stringa	Il tipo di modifica ("INSERT", UPDATE, "DELETE") che l'evento rappresenta.

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.

Nota: questo flusso di eventi di esempio è per un database Oracle, ma è simile per un database MySQL o PostgreSQL.

TEMPO	THIS_IS_MY_PK (int)	FIELD1 (nchar nullable)	FIELD2 (nchar non nullo)>
0	1231535353	pippo	TLV
1	1231535353	NULL	TLV

INSERISCI (T0)

Il payload dei messaggi è costituito dall’intera riga della 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 i 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 come Datastream gestisce l'ordinamento e la coerenza.

Ordinare

Datastream non garantisce l'ordinamento, ma ogni evento contiene la riga completa di dati e il timestamp con il momento in cui i dati sono stati scritti nell'origine. In BigQuery, gli eventi fuori sequenza verranno uniti automaticamente nella sequenza corretta. BigQuery utilizza i metadati degli eventi e un numero di sequenza di modifiche interno (CSN) per applicare gli eventi alla tabella nell'ordine corretto. In Cloud Storage, gli eventi contemporaneamente possono interessare più di un file.

Gli eventi generati in ordine casuale si verificano in base alla progettazione quando viene eseguito il backfill degli eventi per il backfill iniziale dei dati creati all'avvio del flusso.

L'ordine può essere dedotto su base per origine.

Origine	Descrizione
MySQL	Gli eventi che fanno parte del backfill iniziale hanno il campo read_method che inizia con mysql-backfill. Non c'è alcuna implicazione per l'ordine in cui gli eventi vengono ricevuti nel backfill perché possono essere consumati in qualsiasi ordine. Gli eventi che fanno parte della replica in corso hanno il campo read_method impostato su mysql-cdc-binlog. L'ordine può essere dedotto dalla combinazione del campo log_file e del campo log_position che è offset dal file di log. Questa combinazione fornisce un numero univoco e incrementale che identifica l'ordine di funzionamento nel database.
Oracle	Gli eventi che fanno parte del backfill iniziale hanno il campo read_method che inizia con oracle-backfill. L'ordine in cui gli eventi vengono ricevuti all'interno del backfill non ha alcuna implicazione, in quanto 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 (l'ID set di record) e del campo ssn (un numero di sequenza SQL). Questa combinazione fornisce un numero univoco in aumento 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. L'ordine in cui gli eventi vengono ricevuti all'interno del backfill non ha alcuna implicazione, in quanto 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 del campo source_timestamp e del campo lsn (numero di sequenza del log). Questa combinazione fornisce un numero univoco e incrementale che identifica l'ordine di funzionamento nel database.
SQL Server	Gli eventi che fanno parte del backfill iniziale hanno il campo read_method che inizia con sqlserver-backfill. Non c'è alcuna implicazione per l'ordine in cui gli eventi vengono ricevuti nel backfill perché possono essere consumati 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 del campo source_timestamp e del campo lsn (numero di sequenza del log). Questa combinazione fornisce un numero univoco e incrementale che identifica l'ordine di funzionamento nel database.

Coerenza

Datastream garantisce che i dati del database di origine verranno inviati alla destinazione almeno una volta. Gli eventi non verranno persi, ma è possibile che siano presenti eventi duplicati nello stream. La finestra per gli eventi duplicati dovrebbe essere nell'ordine dei minuti e l'identificatore univoco universale (UUID) dell'evento nei metadati evento può essere utilizzato per rilevare i duplicati.

Quando i file di log del database contengono transazioni di cui non è stato eseguito il commit, se viene eseguito il rollback di una qualsiasi transazione, il database lo riflette nei file di log come "inverso" le operazioni DML (Data Manipulation Language). Ad esempio, un'operazione INSERT di cui è stato eseguito il rollback avrà un'operazione DELETE corrispondente. Datastream legge queste operazioni dai file di log.

Informazioni sugli stream

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

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

Stato e stato del flusso

Uno stream può trovarsi in uno dei seguenti stati:

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

Per ulteriori informazioni su questi stati, incluso il modo in cui vengono utilizzati nel ciclo di vita di uno stream, consulta Ciclo di vita dello stream.

Puoi utilizzare i log per trovare ulteriori informazioni sullo stato, come 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 oggetti che rappresentano la struttura degli oggetti definiti nell'origine dati o nella destinazione rappresentati dal profilo di connessione. Ogni oggetto ha metadati sull'oggetto stesso, nonché per ogni campo di dati estratto. Questi metadati sono disponibili tramite l'API Discover.

Passaggi successivi

• Per scoprire di più sugli stream, consulta la sezione Ciclo di vita degli stream.
• Per scoprire come creare uno stream, consulta l'articolo Creare uno stream.