Événements et flux

La hiérarchie des données dans Datastream est la suivante :

  • Un flux, qui comprend une source de données et une destination.
  • Un objet, qui correspond à une partie d'un flux, telle qu'une table provenant d'une base de données spécifique.
  • Un événement, qui correspond à une modification unique générée par un objet spécifique, tel qu'une insertion dans une base de données.

Les flux, les objets et les événements sont associés à des données et à des métadonnées. Ces données et métadonnées peuvent être utilisées à différentes fins.

À propos des événements

Chaque événement se compose de trois types de données :

  • Données d'événement:représentent la modification apportée aux données elles-mêmes par l'objet provenant de la source de flux. Chaque événement contient l'intégralité de la ligne modifiée.
  • Métadonnées génériques : ces métadonnées apparaissent pour chaque événement généré par Datastream utilisé pour des actions, telles que la suppression de données en double dans la destination.
  • Métadonnées spécifiques à la source:ces métadonnées apparaissent pour chaque événement généré par une source de flux spécifique. Ces métadonnées varient selon la source.

Données d'événement

Les données d'événement correspondent à la charge utile de chaque modification provenant d'un objet donné issu d'une source de flux.

Les événements sont au format Avro ou JSON.

Lorsque vous utilisez le format Avro, pour chaque colonne, l'événement contient l'index et la valeur de la colonne. À l'aide de l'index de colonne, le nom de la colonne et le type unifié peuvent être récupérés à partir du schéma dans l'en-tête Avro.

Lorsque vous utilisez le format JSON, pour chaque colonne, l'événement contient le nom et la valeur de la colonne.

Les métadonnées d'événement peuvent servir à collecter des informations sur l'origine de l'événement, et à supprimer les données en double dans la destination et les événements de commande par le consommateur en aval.

Les tableaux suivants listent et décrivent les champs et les types de données des métadonnées d'événement génériques et propres à la source.

Métadonnées génériques

Ces métadonnées sont cohérentes pour tous les types de flux.

Champ Type Avro Type JSON Description
stream_name chaîne chaîne Nom unique du flux tel que défini au moment de la création.
read_method chaîne chaîne

Indique si les données ont été lues à partir de la source à l'aide d'une méthode de capture de données modifiées (CDC, Change Data Capture) dans le cadre d'un remplissage d'historique ou dans le cadre d'une tâche de complément créée lors d'un rollback d'une transaction pendant la réplication CDC.

Les valeurs possibles sont les suivantes :

  • oracle-cdc-logminer
  • oracle-backfill
  • oracle-supplementation
  • mysql-cdc-binlog
  • mysql-backfill-incremental
  • mysql-backfill-fulldump
  • postgres-cdc-wal
  • postgresql-backfill
object chaîne chaîne Nom utilisé pour regrouper différents types d'événements, généralement le nom de la table ou de l'objet dans la source.
schema_key chaîne chaîne Identifiant unique du schéma unifié de l'événement.
uuid chaîne chaîne Identifiant unique de l'événement généré par Datastream.
read_timestamp timestamp-millis chaîne Horodatage (UTC) de la lecture de l'enregistrement par Datastream (horodatage de l'epoch en millisecondes).
source_timestamp timestamp-millis chaîne Horodatage (UTC) de la modification de l'enregistrement dans la source (horodatage de l'epoch en millisecondes).
sort_keys {"type": "array", "items": ["string", "long"]} tableau Tableau des valeurs pouvant être utilisées pour trier les événements dans l'ordre dans lequel ils se sont produits.

Métadonnées spécifiques à la source

Ces métadonnées sont associées aux événements CDC et de remplissage de données d'une base de données source. Pour afficher ces métadonnées, sélectionnez une source dans le menu déroulant ci-dessous.

Source Champ Type Avro Type JSON Description
MySQL log_file chaîne chaîne Fichier journal à partir duquel Datastream extrait les événements dans la réplication CDC.
MySQL log_position long long Oosition du journal (décalage) dans le journal binaire MySQL
MySQL primary_keys tableau de chaînes tableau de chaînes Liste (d'une ou de plusieurs) des noms de colonnes qui constituent la clé primaire de la table. Si la table ne possède pas de clé primaire, ce champ est vide.
MySQL is_deleted boolean boolean
  • Une valeur true indique que la ligne a été supprimée dans la source.
  • Une valeur false signifie que la ligne n'a pas été supprimée.
MySQL database chaîne chaîne Base de données associée à l'événement.
MySQL table chaîne chaîne Table associée à l'événement.
MySQL change_type chaîne chaîne

Type de modification (INSERT, UPDATE-INSERT, UPDATE-DELETE et DELETE) que représente l'événement.
Oracle log_file chaîne chaîne Fichier journal à partir duquel Datastream extrait les événements dans la réplication CDC.
Oracle scn long long Position du journal (décalage) dans le journal des transactions Oracle.
Oracle row_id chaîne chaîne row_id d'Oracle.
Oracle is_deleted boolean boolean
  • Une valeur true indique que la ligne a été supprimée dans la source.
  • Une valeur false signifie que la ligne n'a pas été supprimée.
Oracle database chaîne chaîne Base de données associée à l'événement.
Oracle schema chaîne chaîne Schéma associé à la table de l'événement.
Oracle table chaîne chaîne Table associée à l'événement.
Oracle change_type chaîne chaîne

Type de modification (INSERT, UPDATE-INSERT, UPDATE-DELETE et DELETE) que représente l'événement.
Oracle tx_id chaîne chaîne ID de la transaction à laquelle l'événement appartient.
Oracle rs_id chaîne chaîne ID de l'ensemble d'enregistrements. Le couplage de rs_id et ssn identifie de manière unique une ligne dans V$LOGMNR_CONTENTS. rs_id identifie de manière unique l'enregistrement de relecture qui a généré la ligne.
Oracle ssn long long Numéro de séquence SQL. Ce numéro est utilisé avec rs_id et identifie de manière unique une ligne dans V$LOGMNR_CONTENTS.
PostgreSQL schema chaîne chaîne Schéma associé à la table de l'événement.
PostgreSQL table chaîne chaîne Table associée à l'événement.
PostgreSQL is_deleted booléen boolean
  • Une valeur true indique que la ligne a été supprimée dans la source.
  • Une valeur false signifie que la ligne n'a pas été supprimée.
PostgreSQL change_type chaîne chaîne Type de modification (INSERT, UPDATE, DELETE) que représente l'événement.
PostgreSQL tx_id chaîne chaîne ID de la transaction à laquelle l'événement appartient.
PostgreSQL lsn chaîne chaîne Numéro de séquence du journal pour l'entrée actuelle.
PostgreSQL primary_keys tableau de chaînes tableau de chaînes Liste (d'une ou de plusieurs) des noms de colonnes qui constituent la clé primaire de la table. Si la table ne possède pas de clé primaire, ce champ est vide.
SQL Server table chaîne chaîne Table associée à l'événement.
SQL Server database long long Base de données associée à l'événement.
SQL Server schema tableau de chaînes tableau de chaînes Schéma associé à la table de l'événement.
SQL Server is_deleted booléen booléen
  • Une valeur "true" indique que la ligne a été supprimée dans la source.
  • Une valeur "false" signifie que la ligne n'a pas été supprimée.
SQL Server lsn chaîne chaîne Numéro de séquence du journal de l'événement.
SQL Server tx_id chaîne chaîne ID de la transaction à laquelle l'événement appartient.
SQL Server physical_location Tableau d'entiers Tableau d'entiers Emplacement physique de l'enregistrement de journal décrit par trois entiers: l'ID de fichier, l'ID de page et l'ID de l'emplacement de l'enregistrement.
SQL Server replication_index Tableau de chaînes. Tableau de chaînes. Liste des noms de colonnes d'un indice permettant d'identifier de manière unique une ligne de la table.
SQL Server change_type Chaîne Chaîne

Type de modification ("INSERT", "UPDATE", "DELETE") représenté par l'événement.

Exemple de flux d'événements

Ce flux illustre les événements générés par trois opérations consécutives : INSERT, UPDATE et DELETE, sur une seule ligne d'une table SAMPLE pour une base de données source.

TIME THIS_IS_MY_PK (int) FIELD1 (nchar pouvant être nul) FIELD2 (nchar non nul)>
0 1231535353 foo TLV
1 1231535353 NULL TLV

INSERT (T0)

La charge utile du message consiste en l'intégralité de la nouvelle ligne.

{
  "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",
  }
}

UPDATE (T1)

La charge utile du message consiste en l'intégralité de la nouvelle ligne. Il n'inclut pas les valeurs précédentes.

{
  "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",
  }
}

DELETE (T2)

La charge utile du message consiste en l'intégralité de la nouvelle ligne.

{
  "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",
  }
}

Mise en ordre et cohérence

Cette section explique comment Datastream gère la mise en ordre et la cohérence.

commandes

Datastream ne garantit pas l'ordre, mais chaque événement contient la ligne complète de données et l'horodatage de l'écriture des données dans la source. Dans BigQuery, les événements hors séquence sont automatiquement fusionnés dans la séquence correcte. BigQuery utilise les métadonnées des événements et un numéro de séquence de modification (CSN) interne pour appliquer les événements à la table dans l'ordre correct. Dans Cloud Storage, les événements d'une même période peuvent s'étendre sur plusieurs fichiers.

Les événements générés dans le désordre se produisent dès lors qu'ils sont remplis pour le remplissage initial des données créées au lancement du flux.

L'ordre peut être inféré pour chaque source.

Source Description
MySQL

Le champ read_method des événements qui font partie du remplissage initial commence par mysql-backfill. L'ordre dans lequel les événements sont reçus dans le remplissage n'a aucune incidence, car ils peuvent être consommés dans n'importe quel ordre.

Le champ read_method des événements faisant partie de la réplication en cours est défini sur mysql-cdc-binlog.

L'ordre peut être déduit de la combinaison du champ log_file et du champ log_position qui est un décalage par rapport au fichier journal. Cette combinaison fournit un nombre unique croissant de manière incrémentielle qui identifie l'ordre des opérations dans la base de données.
Oracle

Le champ read_method des événements qui font partie du remplissage initial commence par oracle-backfill. L'ordre dans lequel les événements sont reçus dans le remplissage n'a aucune incidence, car ils peuvent être consommés dans n'importe quel ordre.

Le champ read_method des événements faisant partie de la réplication en cours est défini sur oracle-cdc-logminer.

L'ordre peut être déduit de la combinaison du champ rs_id (ID du jeu d'enregistrements) et du champ ssn (numéro de séquence SQL). Cette combinaison fournit un nombre unique croissant de manière incrémentielle qui identifie l'ordre des opérations dans la base de données.
PostgreSQL

Le champ read_method des événements qui font partie du remplissage initial commence par postgresql-backfill. L'ordre dans lequel les événements sont reçus dans le remplissage n'a aucune incidence, car ils peuvent être consommés dans n'importe quel ordre.

Le champ read_method des événements faisant partie de la réplication en cours est défini sur postgres-cdc-wal.

L'ordre peut être déduit de la combinaison du champ source_timestamp et du champ lsn (numéro de séquence du journal). Cette combinaison fournit un nombre unique croissant de manière incrémentielle qui identifie l'ordre des opérations dans la base de données.
SQL Server

Le champ read_method des événements qui font partie du remplissage initial commence par sqlserver-backfill. L'ordre dans lequel les événements sont reçus dans le remplissage n'a aucune incidence, car ils peuvent être consommés dans n'importe quel ordre.

Le champ read_method des événements faisant partie de la réplication en cours est défini sur sqlserver-cdc.

L'ordre peut être déduit de la combinaison du champ source_timestamp et du champ lsn (numéro de séquence du journal). Cette combinaison fournit un nombre unique croissant de manière incrémentielle qui identifie l'ordre des opérations dans la base de données.

Cohérence

Datastream garantit que les données de la base de données source seront distribuées à la destination au moins une fois. Aucun événement ne sera manqué, mais il est possible que des événements soient dupliqués dans le flux. La période de détection des événements en double doit être de l'ordre de quelques minutes. L'identifiant unique universel (UUID) de l'événement dans les métadonnées de l'événement peut être utilisé pour détecter les doublons.

Lorsque les fichiers journaux de la base de données contiennent des transactions non validées, si des transactions sont annulées, la base de données le reflète dans les fichiers journaux sous la forme d'opérations LMD (langage de manipulation de données) "inverses". Par exemple, une opération INSERT annulée aura une opération DELETE correspondante. Datastream lit ces opérations à partir des fichiers journaux.

À propos des flux

Chaque flux comporte des métadonnées qui décrivent à la fois le flux et la source à partir de laquelle il extrait les données. Ces métadonnées incluent des informations telles que le nom du flux, les profils de connexion source et de destination, etc.

Pour afficher la définition complète de l'objet Stream, consultez la documentation de référence de l'API.

État d'un flux

Un flux peut avoir l'un des états suivants :

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

Vous pouvez utiliser les journaux pour obtenir des informations d'état supplémentaires, telles que le remplissage des tables, le nombre de lignes traitées, etc. Vous pouvez également utiliser l'API FetchStreamErrors pour récupérer les erreurs.

Métadonnées d'objets disponibles en utilisant l'API Discovery

L'API de découverte renvoie des objets qui représentent la structure des objets définis dans la source de données ou la destination représentée par le profil de connexion. Chaque objet possède des métadonnées sur l'objet lui-même, ainsi que pour chaque champ de données qu'il extrait. Ces métadonnées sont disponibles via l'API Discover.

Étape suivante