Eventos y transmisiones

Descripción general

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 un flujo, 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 propósitos.

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 la totalidad de 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 todos los eventos generados por una fuente de transmisión 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 se origina en una fuente de transmisión.

Los eventos están en formato Avro o JSON.

Cuando se trabaja con el formato Avro, el evento contiene el índice y el valor de la columna para cada columna. Con el índice de columna, el nombre de la columna y el tipo unificado se pueden recuperar 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 todas las transmisiones de todo tipo.

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 están asociados con los eventos CDC y de reabastecimiento desde una base de datos de origen. Para ver estos metadatos, selecciona una fuente del menú desplegable 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 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 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 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 e identifica de forma única una fila en V$LOGMNR_CONTENTS.
PostgreSQL schema string string El esquema asociado con la tabla del evento.
PostgreSQL table string string Es la tabla asociada con el evento.
PostgreSQL is_deleted booleano booleana
  • Un valor true indica que la fila se borró en la fuente.
  • Un valor 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 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 El esquema asociado con la tabla del evento.
SQL Server is_deleted booleano booleano
  • 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 La ubicación física del registro, que se describe con tres números enteros: ID de archivo, ID de página y ID de ranura del registro.
SQL Server replication_index Matriz de string Matriz de string Es la lista de nombres de columna de un índice que puede identificar de manera inequívoca una fila de 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

En este flujo, se ilustran los eventos que generan 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

INSERTAR (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 consta de la totalidad de 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 consta de la totalidad de 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",
  }
}

Ordenamiento 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 desordenados se combinarán automáticamente en la secuencia correcta. BigQuery usa los metadatos del evento y un número de secuencia de cambio 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 ordenamiento se puede inferir según la 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 implicación en el orden en el 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 configurado como 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 progresivamente 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 configurado como oracle-cdc-logminer.

El orden se puede inferir de la combinación del campo rs_id (el ID del conjunto de registros) y el campo 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 configurado como postgres-cdc-wal.

El orden se puede inferir mediante 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 progresivamente 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 implicación en el orden en el 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 configurado como sqlserver-cdc.

El orden se puede inferir mediante 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 progresivamente 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. La ventana de los eventos duplicados debe ser del orden de los minutos, y se puede usar el identificador único universal (UUID) del evento en los metadatos del evento para detectar duplicados.

Cuando los archivos de registro de la base de datos contienen transacciones no confirmadas, si alguna transacción se revierte, la base de datos refleja esto en los archivos de registro como “revertir” lenguaje de manipulación de datos (DML). 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 transmisión tiene metadatos que describen tanto la transmisión como la fuente de la que extrae los 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 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 representados por el perfil de conexión. Cada objeto tiene metadatos en el objeto en sí y también en cada campo de datos que extrae. Estos metadatos están disponibles a través de la API de Descubre.

¿Qué sigue?