Eventos y transmisiones

La jerarquía de datos en Datastream es la siguiente:

  • Una transmisión, que consta de una fuente de datos y un destino.
  • Un objeto, que es una parte de una transmisión, como una tabla de una base de datos específica.
  • Un evento, que es un solo cambio generado por un objeto específico, como una inserción de base de datos.

Las transmisiones, los objetos y los eventos tienen datos y metadatos asociados. Estos datos y metadatos se pueden usar para diferentes fines.

Acerca de los eventos

Cada evento consta de tres tipos de datos:

  • Datos del evento: Representan el cambio en los datos del objeto que proviene de la fuente del flujo. Cada evento contiene toda la fila que cambió.
  • Metadatos genéricos: Estos metadatos aparecen en cada evento generado por Datastream y se usan para acciones, como quitar datos duplicados en el destino.
  • Metadatos específicos de la fuente: Estos metadatos aparecen en cada evento generado por una fuente de flujo específica. Estos metadatos varían según la fuente.

Datos de eventos

Los datos de eventos son la carga útil de cada cambio de un objeto determinado que proviene de una fuente de flujo.

Los eventos están en formato Avro o JSON.

Cuando se trabaja con el formato Avro, para cada columna, el evento contiene el índice y el valor de la columna. Con el índice de columnas, se pueden recuperar el nombre de la columna y el tipo unificado del esquema en el encabezado de Avro.

Cuando trabajes con el formato JSON, para cada columna, el evento contendrá el nombre y el valor de la columna.

Los metadatos de los eventos se pueden usar para recopilar información sobre el origen del evento, además de quitar datos duplicados en el destino y ordenar los eventos por el consumidor posterior.

En las siguientes tablas, se enumeran y describen los campos y los tipos de datos de los metadatos de eventos genéricos y específicos de la fuente.

Metadatos genéricos

Estos metadatos son coherentes en las transmisiones de todos los tipos.

Campo Tipo Avro Tipo JSON Descripción
stream_name string string El nombre de transmisión único, como se definió en el momento de la creación.
read_method string string

Indica si los datos se leyeron desde la fuente con un método de captura de datos modificados (CDC), como parte del reabastecimiento histórico o como parte de una tarea complementaria que se crea cuando una transacción se revierte durante la replicación de CDC.

Estos son algunos de los valores posibles:

  • oracle-cdc-logminer
  • oracle-backfill
  • oracle-supplementation
  • mysql-cdc-binlog
  • mysql-backfill-incremental
  • mysql-backfill-fulldump
  • postgres-cdc-wal
  • postgresql-backfill
object string string Es el nombre que se usa para agrupar diferentes tipos de eventos, por lo general, el nombre de la tabla o el objeto en la fuente.
schema_key string string Es el identificador único del esquema unificado del evento.
uuid string string Es un identificador único para el evento que genera Datastream.
read_timestamp timestamp-millis string La marca de tiempo (UTC) de cuando Datastream leyó el registro (la marca de tiempo de época en milisegundos).
source_timestamp timestamp-millis string La marca de tiempo (UTC) de cuando el registro cambió en la fuente (la marca de tiempo de época en milisegundos).
sort_keys {"type": "array", "items": ["string", "long"]} array Es un array de valores que se puede usar para ordenar los eventos en el orden en que ocurrieron.

Metadatos específicos de la fuente

Estos metadatos se asocian con la CDC y los eventos de reabastecimiento de una base de datos de origen. Para ver estos metadatos, selecciona una fuente en el menú desplegable que aparece a continuación.

Fuente Campo Tipo Avro Tipo JSON Descripción
MySQL log_file string string El archivo de registro del que Datastream extrae eventos en la replicación de CDC.
MySQL log_position long long La posición del registro (compensación) en el registro binario de MySQL.
MySQL primary_keys arreglo de strings arreglo de strings Es la lista de (uno o más) nombres de columna que conforman la clave primaria de las tablas. Si la tabla no tiene una clave primaria, este campo estará vacío.
MySQL is_deleted booleana booleana
  • Un valor true indica que la fila se borró en la fuente.
  • Un valor de false significa que la fila no se borró.
MySQL database string string Es la base de datos asociada con el evento.
MySQL table string string Es la tabla asociada con el evento.
MySQL change_type string string

Es el tipo de cambio (INSERT, UPDATE-INSERT, UPDATE-DELETE y DELETE) que representa el evento.
Oracle log_file string string El archivo de registro del que Datastream extrae eventos en la replicación de CDC.
Oracle scn long long La posición del registro (compensación) en el registro de transacciones de Oracle.
Oracle row_id string string row_id de Oracle.
Oracle is_deleted booleana booleana
  • Un valor true indica que la fila se borró en la fuente.
  • Un valor de false significa que la fila no se borró.
Oracle database string string Es la base de datos asociada con el evento.
Oracle schema string string Es el esquema asociado con la tabla del evento.
Oracle table string string Es la tabla asociada con el evento.
Oracle change_type string string

Es el tipo de cambio (INSERT, UPDATE-INSERT, UPDATE-DELETE y DELETE) que representa el evento.
Oracle tx_id string string El ID de transacción al que pertenece el evento.
Oracle rs_id string string Es el ID del conjunto de registros. La vinculación de rs_id y ssn identifica de forma única una fila en V$LOGMNR_CONTENTS. rs_id identifica de forma única el registro de rehacer que generó la fila.
Oracle ssn long long Un número de secuencia de SQL. Este número se usa con rs_id y, además, identifica de forma única una fila en V$LOGMNR_CONTENTS.
PostgreSQL schema string string Es el esquema asociado con la tabla del evento.
PostgreSQL table string string Es la tabla asociada con el evento.
PostgreSQL is_deleted boolean booleana
  • Un valor true indica que la fila se borró en la fuente.
  • Un valor de false significa que la fila no se borró.
PostgreSQL change_type string string Es el tipo de cambio (INSERT, UPDATE, DELETE) que representa el evento.
PostgreSQL tx_id string string El ID de transacción al que pertenece el evento.
PostgreSQL lsn string string Es el número de secuencia del registro de la entrada actual.
PostgreSQL primary_keys arreglo de strings arreglo de strings Es la lista de (uno o más) nombres de columna que conforman la clave primaria de las tablas. Si la tabla no tiene una clave primaria, este campo estará vacío.
SQL Server table string string Es la tabla asociada con el evento.
SQL Server database long long Es la base de datos asociada con el evento.
SQL Server schema arreglo de strings arreglo de strings Es el esquema asociado con la tabla del evento.
SQL Server is_deleted boolean boolean
  • Un valor verdadero indica que la fila se borró en la fuente.
  • Un valor falso significa que la fila no se borró.
SQL Server lsn string string Es el número de secuencia del registro del evento.
SQL Server tx_id string string El ID de transacción al que pertenece el evento.
SQL Server physical_location Array de números enteros Array de números enteros Es la ubicación física del registro de registro que se describe con tres números enteros: el ID de archivo, el ID de página y el ID de inserción del registro.
SQL Server replication_index Matriz de string Matriz de string Es la lista de nombres de columnas de un índice que puede identificar de forma inequívoca una fila en la tabla.
SQL Server change_type String String

Es el tipo de cambio ("INSERT", "UPDATE", "DELETE") que representa el evento.

Ejemplo de un flujo de eventos

Este flujo ilustra los eventos generados por tres operaciones consecutivas: INSERT, UPDATE y DELETE, en una sola fila de una tabla SAMPLE para una base de datos de origen.

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

INSERT (T0)

La carga útil del mensaje consiste en toda la fila nueva.

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

ACTUALIZACIÓN (T1)

La carga útil del mensaje consiste en toda la fila nueva. No incluye valores anteriores.

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

BORRAR (T2)

La carga útil del mensaje consiste en toda la fila nueva.

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

Orden y coherencia

En esta sección, se explica cómo Datastream controla el orden y la coherencia.

Pedidos

Datastream no garantiza el orden, pero cada evento contiene la fila completa de datos y la marca de tiempo de cuando se escribieron los datos en la fuente. En BigQuery, los eventos fuera de orden se combinarán automáticamente en la secuencia correcta. BigQuery usa los metadatos del evento y un número de secuencia de cambios interno (CSN) para aplicar los eventos a la tabla en el orden correcto. En Cloud Storage, los eventos de la misma hora pueden abarcar más de un archivo.

Los eventos que se generan fuera de orden ocurren según el diseño cuando los eventos se reabastecen en el reabastecimiento inicial de datos que se crean cuando se inicia la transmisión.

El orden se puede inferir en cada fuente.

Fuente Descripción
MySQL

Los eventos que forman parte del reabastecimiento inicial tienen el campo read_method que comienza con mysql-backfill. No hay ninguna implicación en el orden en que se reciben los eventos dentro del reabastecimiento, ya que se pueden consumir en cualquier orden.

Los eventos que forman parte de la replicación en curso tienen el campo read_method establecido en mysql-cdc-binlog.

El orden se puede inferir mediante la combinación del campo log_file y el campo log_position que está desplazado del archivo de registro. Esta combinación proporciona un número único que aumenta de forma incremental y que identifica el orden de operación en la base de datos.
Oracle

Los eventos que forman parte del reabastecimiento inicial tienen el campo read_method que comienza con oracle-backfill. No hay ninguna implicación en el orden en que se reciben los eventos dentro del reabastecimiento, ya que se pueden consumir en cualquier orden.

Los eventos que forman parte de la replicación en curso tienen el campo read_method establecido en oracle-cdc-logminer.

El orden se puede inferir mediante la combinación de los campos rs_id (el ID del conjunto de registros) y ssn (un número de secuencia de SQL). Esta combinación proporciona un número único que aumenta de forma incremental y que identifica el orden de operación en la base de datos.
PostgreSQL

Los eventos que forman parte del reabastecimiento inicial tienen el campo read_method que comienza con postgresql-backfill. No hay ninguna implicación en el orden en que se reciben los eventos dentro del reabastecimiento, ya que se pueden consumir en cualquier orden.

Los eventos que forman parte de la replicación en curso tienen el campo read_method establecido en postgres-cdc-wal.

El orden se puede inferir a partir de la combinación del campo source_timestamp y el campo lsn (número de secuencia de registro). Esta combinación proporciona un número único que aumenta de forma incremental y que identifica el orden de operación en la base de datos.
SQL Server

Los eventos que forman parte del reabastecimiento inicial tienen el campo read_method que comienza con sqlserver-backfill. No hay ninguna implicación en el orden en que se reciben los eventos dentro del reabastecimiento, ya que se pueden consumir en cualquier orden.

Los eventos que forman parte de la replicación en curso tienen el campo read_method establecido en sqlserver-cdc.

El orden se puede inferir a partir de la combinación del campo source_timestamp y el campo lsn (número de secuencia de registro). Esta combinación proporciona un número único que aumenta de forma incremental y que identifica el orden de operación en la base de datos.

Coherencia

Datastream garantiza que los datos de la base de datos de origen se entreguen al destino al menos una vez. No se perderá ningún evento, pero es posible que haya eventos duplicados en la transmisión. El período para los eventos duplicados debe ser de minutos, y el identificador único universal (UUID) del evento en los metadatos del evento se puede usar para detectar duplicados.

Cuando los archivos de registro de la base de datos contienen transacciones sin confirmar, si se revierten algunas transacciones, la base de datos lo refleja en los archivos de registro como operaciones de lenguaje de manipulación de datos (DML) "inversas". Por ejemplo, una operación INSERT revertida tendrá una operación DELETE correspondiente. Datastream lee estas operaciones de los archivos de registro.

Información acerca de las transmisiones

Cada flujo tiene metadatos que describen el flujo y la fuente de la que extrae datos. Estos metadatos incluyen información como el nombre de la transmisión, los perfiles de conexión de origen y destino, etcétera.

Para ver la definición completa del objeto Transmisión, consulta la documentación de Referencia de la API.

Estado y condición de la transmisión

Una transmisión puede estar en uno de los siguientes estados:

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

Puedes usar los registros para encontrar información de estado adicional, como el reabastecimiento de las tablas, la cantidad de filas procesadas, etcétera. También puedes usar la API de FetchStreamErrors para recuperar errores.

Metadatos de objeto disponibles con la API de descubrimiento

La API de descubrimiento muestra objetos que representan la estructura de los objetos definidos en la fuente de datos o el destino que representa el perfil de conexión. Cada objeto tiene metadatos sobre el objeto en sí, así como para cada campo de datos que extrae. Estos metadatos están disponibles a través de la API de Descubre.

¿Qué sigue?