Eventos y transmisiones

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

  • Un flujo, 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 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
  • 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 cadena 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 change_stream_name cadena cadena Es el flujo de cambios de Spanner.
Spanner table cadena cadena La tabla de Spanner.
Spanner server_transaction_id cadena cadena Es el identificador de la transacción asociado con el evento.
Spanner record_sequence cadena cadena Es la secuencia de registros asociada con el evento.
Spanner mod_index cadena cadena 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 system_transaction cadena cadena Indica si la transacción es del sistema.
Spanner number_of_records_in_transaction long long Es la cantidad de registros en la transacción asociada.
Spanner value_capture_type enum enum Es el tipo de captura de valor del flujo de cambios.
Spanner mod_type enum enum Indica si el registro era un INSERT, UPDATE o DELETE.
Spanner primary_keys array array 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 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 combinan en la secuencia correcta de forma automática. BigQuery usa los metadatos de los eventos 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 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 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 (para la replicación basada en binlog) o se establece en backfill (para la replicación basada en GTID). 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 (para la replicación basada en binlog) o cdc (para la replicación basada en GTID).

Para la replicación basada en binlog, el orden se puede inferir por la combinación de los campos log_file y log_position. Para la replicación basada en GTID, el orden se puede inferir con la combinación de los campos binlog_file y binlog_position (o el campo gtid). Esta combinación proporciona un número único que aumenta de forma incremental y que identifica el orden de las operaciones 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 por 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 la 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 por 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 la 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 por 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 la operación en la base de datos.

Cuando se replica en BigQuery, la hora de creación de la base de datos también se usa para garantizar el orden correcto. Esto es importante en situaciones en las que la instancia de la base de datos de origen puede cambiar, por ejemplo, durante las migraciones o la conmutación por error a una réplica.
Salesforce

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 que ocurran en el mismo segundo.
MongoDB

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

El orden se puede determinar con la combinación de los campos commit_timestamp, record_sequence y mod_index. Esta combinación proporciona un valor único que aumenta de forma incremental y que identifica el orden de las operaciones 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 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?