Événements et flux

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

  • Un flux, qui se compose d'une source de données et d'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.

Des données et des métadonnées sont associées aux flux, aux objets et aux événements. 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 : elles représentent la modification des données elles-mêmes à partir de l'objet provenant de la source du flux. Chaque événement contient l'intégralité de la ligne qui a été 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, l'événement contient l'index et la valeur de chaque 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, l'événement contient le nom et la valeur de chaque 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 pour les métadonnées d'événement génériques et spécifiques à 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 qu'il a été défini lors 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
  • salesforce-cdc
  • salesforce-backfill
object chaîne chaîne Nom utilisé pour regrouper différents types d'événements. Il s'agit généralement du 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'historique 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 lors de 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'un ou de plusieurs noms de colonnes qui constituent la clé primaire des tables. Si la table ne comporte 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 lors de 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 appartient l'événement.
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 redo qui a généré la ligne.
Oracle ssn long long Numéro de séquence SQL. Ce nombre 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 appartient l'événement.
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'un ou de plusieurs noms de colonnes qui constituent la clé primaire des tables. Si la table ne comporte 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 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.
SQL Server lsn chaîne chaîne Numéro de séquence du journal pour l'événement.
SQL Server tx_id chaîne chaîne ID de la transaction à laquelle appartient l'événement.
SQL Server physical_location tableau d'entiers tableau d'entiers Emplacement physique de l'enregistrement du journal décrit par trois entiers : ID de fichier, ID de page et ID d'emplacement de l'enregistrement.
SQL Server replication_index tableau de chaînes tableau de chaînes Liste des noms de colonnes d'un index qui peut identifier de manière unique une ligne dans la table.
SQL Server change_type chaîne chaîne

Type de modification (INSERT, UPDATE, DELETE) que représente l'événement.
Salesforce object_name chaîne chaîne

Nom de l'objet Salesforce associé à l'événement.
Salesforce domain chaîne chaîne

Nom du domaine associé à l'événement.
Salesforce 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.
Salesforce change_type chaîne chaîne

Type de modification (INSERT, UPDATE, DELETE) que représente l'événement.
Salesforce primary_keys tableau de chaînes tableau de chaînes Liste des noms de colonnes qui constituent la clé primaire des tables. Si la table ne comporte pas de clé primaire, ce champ est vide.
MongoDB database chaîne chaîne Base de données associée à l'événement.
MongoDB collection chaîne chaîne Collection associée à l'événement. Les collections sont analogues aux tables dans les bases de données relationnelles.
MongoDB change_type chaîne chaîne Type de modification (CREATE, UPDATE et DELETE) que représente l'événement.
MongoDB 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.
MongoDB primary_keys tableau de chaînes tableau de chaînes Le champ _id qui sert de clé primaire pour chaque document d'une collection.

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 est constituée de 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 est constituée de l'intégralité de la nouvelle ligne. Elle 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 est constituée de 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 des événements, mais chacun d'eux contient la ligne de données complète 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 le bon ordre. BigQuery utilise les métadonnées d'événement et un numéro de séquence de modification (CSN) interne pour appliquer les événements à la table dans le bon ordre. 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 déduit pour chaque source.

Source Description
MySQL

Les événements qui font partie du remplissage initial ont un champ read_method commençant par mysql-backfill. L'ordre dans lequel les événements sont reçus dans le remplissage n'a aucune importance, car ils peuvent être traités dans n'importe quel ordre.

Pour les événements qui font partie de la réplication en cours, le champ read_method 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

Les événements qui font partie du remplissage initial ont un champ read_method commençant par oracle-backfill. L'ordre dans lequel les événements sont reçus dans le remplissage n'a aucune importance, car ils peuvent être traités dans n'importe quel ordre.

Pour les événements qui font partie de la réplication en cours, le champ read_method 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

Les événements qui font partie du remplissage initial ont un champ read_method commençant par postgresql-backfill. L'ordre dans lequel les événements sont reçus dans le remplissage n'a aucune importance, car ils peuvent être traités dans n'importe quel ordre.

Pour les événements qui font partie de la réplication en cours, le champ read_method 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

Les événements qui font partie du remplissage initial ont un champ read_method commençant par sqlserver-backfill. L'ordre dans lequel les événements sont reçus dans le remplissage n'a aucune importance, car ils peuvent être traités dans n'importe quel ordre.

Pour les événements qui font partie de la réplication en cours, le champ read_method 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.
Salesforce (bêta)

L'ordre peut être déterminé en utilisant le source_timestamp de l'enregistrement comme clé de tri. La résolution du code temporel dans Salesforce est d'une seconde, mais il ne peut pas y avoir deux événements de modification pour le même enregistrement au cours de la même seconde.
MongoDB (aperçu)

L'ordre peut être déterminé à l'aide du champ ts dans le journal des opérations ou du champ clusterTime dans le flux de modifications de l'enregistrement. Les champs sont uniques pour chaque enregistrement.

Cohérence

Datastream s'assure que les données de la base de données source sont transmises à la destination au moins une fois. Aucun événement n'est manqué, mais il est possible que des événements en double apparaissent dans le flux. La période pour les é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 de langage de manipulation de données (LMD) "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, ainsi que les profils de connexion source et de destination.

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 trouver des informations supplémentaires sur l'état, comme le remplissage des tables ou le nombre de lignes traitées. 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 Discover renvoie des objets qui représentent la structure des objets définis dans la source ou la destination de données représentée par le profil de connexion. Chaque objet comporte 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 à l'aide de l'API Discover.

Étapes suivantes