Eventos y transmisiones

Datastream organiza los datos replicados en una jerarquía de tres niveles de flujos, objetos y eventos. Un flujo conecta una fuente de datos con un destino, mientras que un objeto representa una entidad de origen específica en ese flujo, como una tabla de base de datos. Un evento captura un solo cambio de datos de un objeto, como una inserción de base de datos.

Cada evento incluye datos y metadatos que identifican su flujo y objeto de origen. Puedes usar estos metadatos para hacer un seguimiento de los orígenes de los cambios, quitar registros duplicados en tu destino y mantener el orden entre los consumidores downstream.

Acerca de los eventos

Cada evento consta de tres tipos de datos:

  • Datos de eventos: Representan el cambio en los datos del objeto que se origina en la fuente de transmisión. Cada evento contiene la totalidad de la fila que cambió.
  • Metadatos genéricos: Estos metadatos aparecen en cada evento que genera Datastream y que se usa para acciones, como quitar datos duplicados en el destino.
  • Metadatos específicos de la fuente: Estos metadatos aparecen en cada evento que genera 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, para cada columna, el evento contiene el índice y el valor de la columna. Con el índice de la columna, se pueden recuperar el nombre de la columna y el tipo unificado del esquema en el encabezado de Avro.

Cuando se trabaja 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 de los metadatos de eventos genéricos y específicos de la fuente.

Metadatos genéricos

Estos metadatos son coherentes en todos los tipos de transmisiones.

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:

  • cdc
  • backfill
  • oracle-cdc-logminer
  • oracle-backfill
  • oracle-supplementation
  • mysql-cdc-binlog
  • mysql-backfill-incremental
  • mysql-backfill-fulldump
  • postgres-cdc-wal
  • postgresql-backfill
  • sqlserver-cdc
  • sqlserver-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 cadena Es un identificador único para el esquema unificado del evento.
uuid cadena 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 los eventos de CDC y 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 cadena Es el archivo de registro del que Datastream extrae eventos en la replicación de CDC cuando se usa la replicación basada en binlog.
MySQL log_position long long Es la posición del registro (desplazamiento) en el registro binario de MySQL cuando se usa la replicación basada en binlog.
MySQL binlog_file string cadena Es el archivo de registro binario del que Datastream extrae eventos en la replicación de CDC cuando se usa la replicación basada en GTID.
MySQL binlog_position long long Es la posición (desplazamiento) en el registro binario de MySQL cuando se usa la replicación basada en GTID.
MySQL gtid string cadena Es el identificador de transacciones global (GTID) que identifica de forma inequívoca la transacción del evento cuando se usa la replicación basada en GTID.
MySQL datastream_master_server_uuid string cadena Es el UUID de la instancia del servidor de origen de MySQL desde la que Datastream lee los eventos cuando se usa la replicación basada en GTID.
MySQL datastream_master_server_id long long Es el ID de la instancia del servidor de origen de MySQL desde la que Datastream lee los eventos cuando se usa la replicación basada en GTID.
MySQL primary_keys Array de cadenas Array de cadenas Es la lista de nombres de columnas (uno o más) que conforman la clave primaria de la tabla. 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 no se borró la fila.
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 cadena 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 no se borró la fila.
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 unión de rs_id y ssn identifica de forma única una fila en V$LOGMNR_CONTENTS. rs_id identifica de forma inequívoca 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 cadena string Es el esquema asociado con la tabla del evento.
PostgreSQL table cadena 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 de false significa que no se borró la fila.
PostgreSQL change_type cadena cadena Es el tipo de cambio (INSERT, UPDATE, DELETE) que representa el evento.
PostgreSQL tx_id cadena string El ID de transacción al que pertenece el evento.
PostgreSQL lsn cadena cadena Es el número de secuencia de registro de la entrada actual.
PostgreSQL primary_keys Array de cadenas Array de cadenas Es la lista de nombres de columnas (uno o más) que conforman la clave primaria de la tabla. Si la tabla no tiene una clave primaria, este campo estará vacío.
SQL Server table cadena 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 Array de cadenas Array de cadenas Es el esquema asociado con la tabla del evento.
SQL Server is_deleted booleano booleana
  • Un valor true indica que la fila se borró en la fuente.
  • Un valor de false significa que no se borró la fila.
SQL Server lsn cadena cadena Es el número de secuencia de registro del evento.
SQL Server tx_id cadena 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 anotaciones, que se describe con tres números enteros: el ID del archivo, el ID de la página y el ID de la ranura del registro.
SQL Server replication_index Array de cadenas Array de cadenas Es la lista de nombres de columnas de un índice que puede identificar de forma inequívoca una fila de la tabla.
SQL Server change_type cadena cadena

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

Spanner commit_timestamp timestamp-micros cadena Es la marca de tiempo de confirmación del evento.
Spanner snapshot booleano booleano Indica si el evento es un evento de instantánea de reabastecimiento.
Spanner project_id cadena cadena Es el identificador del proyecto de Spanner.
Spanner instance_id cadena cadena Es el identificador de la instancia de Spanner.
Spanner database_id cadena cadena Es el identificador de la base de datos de Spanner.
Spanner schema cadena string Es el esquema asociado con la tabla del evento. Está vacío si la tabla no está en un esquema con nombre.
Spanner table cadena cadena La tabla de Spanner.
Spanner change_stream_name cadena cadena Es el flujo de cambios de Spanner.
Spanner server_transaction_id cadena cadena Es el identificador de la transacción asociado con el evento.
Spanner record_sequence long o string long o string Es la secuencia de registros asociada con el evento. Para los flujos de cambios creados con el modo de partición IMMUTABLE_KEY_RANGE, el valor es un número de secuencia numérico de tipo long. Para los flujos de cambios creados con el modo de partición MUTABLE_KEY_RANGE, el valor es la cadena record_sequence del registro de cambios de datos, como 1cac8f3f38eeaf53-00000000.
Spanner mod_number long long Es el número de modificación asociado con el evento.
Spanner transaction_tag cadena cadena Es la etiqueta de la transacción asociada.
Spanner number_of_records_in_transaction long long Es la cantidad de registros en la transacción asociada.
Spanner value_capture_type cadena cadena Es el tipo de captura de valor del flujo de cambios. Los valores posibles son NEW_ROW y NEW_ROW_AND_OLD_VALUES.
Spanner change_type cadena cadena Es el tipo de cambio (INSERT, UPDATE o DELETE) que representa el evento.
Spanner primary_keys Array de cadenas Array de cadenas Es la lista de columnas de clave primaria de la tabla.
Spanner is_deleted booleano booleano Indica si el cambio representa un evento DELETE.
Salesforce object_name cadena cadena

Es el nombre del objeto de Salesforce asociado con el evento.

Salesforce domain cadena cadena

Es el nombre del dominio asociado con el evento.

Salesforce is_deleted booleano booleana
  • Un valor true indica que la fila se borró en la fuente.
  • Un valor de false significa que no se borró la fila.
Salesforce change_type cadena cadena

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

Salesforce primary_keys Array de cadenas Array de cadenas Es la lista de nombres de columnas que conforman la clave primaria de las tablas. Si la tabla no tiene una clave primaria, este campo estará vacío.
MongoDB database cadena string Es la base de datos asociada con el evento.
MongoDB collection cadena cadena Es la colección asociada con el evento. Las colecciones son similares a las tablas en las bases de datos relacionales.
MongoDB change_type cadena cadena Es el tipo de cambio (CREATE, UPDATE y DELETE) que representa el evento.
MongoDB is_deleted booleano booleana
  • Un valor true indica que la fila se borró en la fuente.
  • Un valor de false significa que no se borró la fila.
MongoDB primary_keys Array de cadenas Array de cadenas El campo _id, que actúa como la clave primaria de cada documento de una colección.

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

UPDATE (T1)

La carga útil del mensaje consiste en 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 consiste en 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 la entrega de eventos en orden, pero cada evento contiene la fila completa de datos, la marca de tiempo de cuando se escribieron los datos en la fuente y los metadatos de orden.

Los eventos que forman parte de un reabastecimiento inicial tienen el campo read_method establecido en backfill o que termina con -backfill, -fulldump o -incremental. Los eventos de reabastecimiento se generan de forma desordenada por diseño y se pueden consumir en cualquier orden.

Los eventos que forman parte de la replicación continua de captura de datos modificados (CDC) tienen el campo read_method establecido en cdc o un valor de CDC específico de la fuente, como mysql-cdc-binlog, oracle-cdc-logminer, postgres-cdc-wal, sqlserver-cdc o salesforce-cdc. La forma en que ordenas los eventos de replicación en curso en todas las fuentes depende de tu destino:

Destino Descripción
BigQuery

La forma en que se ordenan los eventos en BigQuery depende del modo de escritura que configures para tu transmisión:

  • Modo de escritura de combinación: BigQuery combina automáticamente los eventos desordenados en la secuencia correcta con los metadatos del evento y un número de secuencia de cambio (CSN) interno. Las tablas sin una clave primaria se escriben en modo de solo anexar.
  • Modo de escritura de solo agregado, incluidas las tablas de Apache Iceberg: Datastream agrega eventos de cambio a la tabla de destino y completa la columna datastream_metadata STRUCT. Para determinar el orden en el que se produjeron los eventos en la fuente, ordénalos con el campo datastream_metadata.change_sequence_number o el campo de array datastream_metadata.sort_keys.
Cloud Storage

En Cloud Storage, los eventos del mismo período pueden abarcar más de un archivo. Para determinar el orden en el que se produjeron los eventos en la fuente, ordénalos con el campo de array sort_keys en los metadatos genéricos.

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 existe la posibilidad de que haya eventos duplicados en la transmisión. La ventana 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.

Sin embargo, no confíes únicamente en el UUID para anular la duplicación de eventos downstream. Si se produce una interrupción en la canalización, Datastream vuelve a leer el registro de origen desde el último punto de control guardado para garantizar la entrega. Debido a que Datastream genera UUID de forma dinámica cuando lee un evento, este tipo de reintento genera UUID nuevos para los mismos datos de origen. Además, durante las operaciones masivas en la base de datos de origen, varias filas distintas pueden compartir el mismo número de secuencia de cambio (CSN).

Para anular la duplicación de datos de forma confiable, particiona los eventos por las claves primarias de la tabla de origen y agrúpalos con el número de secuencia de cambio (CSN) (el campo change_sequence_number). Esto garantiza que los reintentos del mismo evento se contraigan correctamente, a la vez que se conservan las actualizaciones de filas legítimamente distintas de las transacciones masivas.

Cuando los archivos de registro de la base de datos contienen transacciones no confirmadas, si se revierte alguna transacción, 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.

Acerca de las transmisiones

Cada flujo tiene metadatos que describen tanto el flujo como la fuente de la que extrae los 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 descubrimiento 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 con la API de descubrimiento.

¿Qué sigue?