Eventos y transmisiones

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

  • Una transmisión, que se compone 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 propósitos.

Acerca de los eventos

Cada evento consta de tres tipos de datos:

  • Datos del evento: Representan el cambio en los datos en sí del objeto que se originó en la fuente de la transmisión. 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 cada evento generado por una fuente de transmisión específica. Estos metadatos varían según la fuente.

Datos de eventos

Los datos del evento 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, para cada columna, el evento contiene el índice y el valor de la columna. Con el índice de columna, se pueden recuperar el nombre de la columna y el tipo unificado del esquema en el encabezado de Avro.

Cuando trabajas con el formato JSON, para cada columna, el evento contiene 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 para los metadatos de eventos genéricos y específicos de la fuente.

Metadatos genéricos

Estos metadatos son coherentes en todas 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
  • salesforce-cdc
  • salesforce-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 del 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 según el orden en que ocurrieron.

Metadatos específicos de la fuente

Estos metadatos se asocian con eventos de CDC y reabastecimiento de una base de datos fuente. 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 nombres de columna (uno o más) que componen la clave primaria de la tabla. Si la tabla no tiene una clave primaria, este campo está vacío.
MySQL is_deleted booleana booleana
  • Un valor de true indica que la fila se borró en la fuente.
  • Un valor de false significa que no se borró la fila.
MySQL database string string Es la base de datos asociada al 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 Es el row_id de Oracle.
Oracle is_deleted booleana booleana
  • Un valor de true indica que la fila se borró en la fuente.
  • Un valor de false significa que no se borró la fila.
Oracle database string string Es la base de datos asociada al 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 combinació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 Es 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 booleano booleana
  • Un valor de true indica que la fila se borró en la fuente.
  • Un valor de false significa que no se borró la fila.
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 nombres de columna (uno o más) que componen la clave primaria de la tabla. Si la tabla no tiene una clave primaria, este campo está 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 al evento.
SQL Server schema arreglo de strings arreglo de strings Es el esquema asociado con la tabla del evento.
SQL Server is_deleted booleano booleana
  • Un valor de true indica que la fila se borró en la fuente.
  • Un valor de false significa que no se borró la fila.
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 Ubicación física del registro de 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 arreglo de strings arreglo de strings Es la lista de nombres de columnas de un índice que puede identificar de forma única una fila en la tabla.
SQL Server change_type string string

Es el tipo de cambio (INSERT, UPDATE, DELETE) que representa el evento.
Salesforce object_name string string

Es el nombre del objeto de Salesforce asociado al evento.
Salesforce domain string string

Es el nombre del dominio asociado al evento.
Salesforce is_deleted booleano booleana
  • Un valor de true indica que la fila se borró en la fuente.
  • Un valor de false significa que no se borró la fila.
Salesforce change_type string string

Es el tipo de cambio (INSERT, UPDATE, DELETE) que representa el evento.
Salesforce primary_keys arreglo de strings arreglo de strings Es la lista de nombres de columna que componen la clave primaria de las tablas. Si la tabla no tiene una clave primaria, este campo está vacío.
MongoDB database string string Es la base de datos asociada al evento.
MongoDB collection string string Es la colección asociada al evento. Las colecciones son análogas a las tablas en las bases de datos relacionales.
MongoDB change_type string string Tipo de cambio (CREATE, UPDATE y DELETE) que representa el evento.
MongoDB is_deleted booleano booleana
  • Un valor de true indica que la fila se borró en la fuente.
  • Un valor de false significa que no se borró la fila.
MongoDB primary_keys arreglo de strings arreglo de strings El campo _id que actúa como clave primaria para cada documento de una colección.

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 incluye 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": "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 incluye 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",
  }
}

DELETE (T2)

La carga útil del mensaje incluye 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",
  }
}

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 cuándo se escribieron los datos en la fuente. En BigQuery, los eventos desordenados se combinan automáticamente en la secuencia correcta. BigQuery usa los metadatos del evento y un número de secuencia de cambio (CSN) interno para aplicar los eventos a la tabla en el orden correcto. En Cloud Storage, los eventos del mismo período 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 fuente por fuente.

Fuente Descripción
MySQL

Los eventos que forman parte del reabastecimiento inicial tienen el campo read_method que comienza con mysql-backfill. El orden en que se reciben los eventos en el reabastecimiento no tiene ninguna implicación, 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 a partir de la combinación del campo log_file y el campo log_position que se desplaza desde el 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. El orden en que se reciben los eventos en el reabastecimiento no tiene ninguna implicación, 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 a partir 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. El orden en que se reciben los eventos en el reabastecimiento no tiene ninguna implicación, 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 del 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. El orden en que se reciben los eventos en el reabastecimiento no tiene ninguna implicación, 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 del 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.
Salesforce (vista previa)

El orden se puede determinar usando el source_timestamp del registro como clave de ordenamiento. La marca de tiempo en Salesforce tiene una resolución de un segundo, pero no puede haber dos eventos de cambio para el mismo registro en el mismo segundo.
MongoDB (versión preliminar)

El orden se puede determinar con el campo ts en el registro de operaciones o el campo clusterTime en el flujo de cambios del registro. Los campos son únicos para cada registro.

Coherencia

Datastream garantiza que los datos de la base de datos de origen se entreguen al destino al menos una vez. No se pierde ningún evento, pero es posible que haya eventos duplicados en la transmisión. La ventana para los eventos duplicados debe ser del orden de 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 sin confirmar, si se revierte alguna transacción, la base de datos refleja esto 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.

Acerca de las transmisiones

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

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 o la cantidad de filas procesadas. También puedes usar la API de FetchStreamErrors para recuperar errores.

Metadatos de objeto disponibles con la API de descubrimiento

La API de Discover devuelve 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 descubrimiento.

¿Qué sigue?