Eventos y transmisiones

Descripción general

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 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, objetos y 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 originó 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 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.

Nota: Cuando Datastream convierte datos al formato Avro, los caracteres especiales en los nombres de columna se reemplazan por guiones bajos. Esto puede generar nombres de columnas duplicados y provocar fallas en las transmisiones. Para obtener más información sobre las convenciones de nombres en Avro, consulta la documentación de Apache Avro.

Cuando trabajas con el formato JSON, el evento contiene el nombre y el valor de cada columna para cada 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 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, es 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	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.

Todas las fuentes MySQL Oracle PostgreSQL SQL Server

Origen	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	boolean	boolean	Un valor true indica que se borró la fila en la fuente. Un valor false significa que la fila no se borró.
MySQL	database	string	string	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. En la replicación basada en filas de MySQL, cada evento para una fila con un cambio de clave primaria contiene dos imágenes: una imagen de “antes”, cuyas columnas se comparan cuando se busca la fila que se actualizará, y una imagen de “después”, que contiene los cambios. Por ejemplo, para el cambio UPDATE-DELETE, UPDATE-DELETE es la imagen de “antes” y UPDATE-INSERT es la imagen de “después”. Obtén más información sobre la replicación basada en filas de MySQL.
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	boolean	boolean	Un valor true indica que se borró la fila en la fuente. Un valor false significa que la fila no se borró.
Oracle	database	string	string	La base de datos asociada con el evento.
Oracle	schema	string	string	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. En la replicación basada en filas de Oracle, cada evento para una fila con un cambio de clave primaria contiene dos imágenes: una imagen de “antes”, cuyas columnas se comparan cuando se busca la fila que se actualizará, y una imagen de “después”, que contiene los cambios. Por ejemplo, para el cambio UPDATE-DELETE, UPDATE-DELETE es la imagen de “antes” y UPDATE-INSERT es la imagen de “después”. Obtén más información sobre la replicación basada en filas de Oracle.
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. El acoplamiento 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	boolean	boolean	Un valor true indica que se borró la fila 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. En el caso de la replicación basada en filas de PostgreSQL, cada evento de una fila con un cambio de clave primaria contiene dos imágenes: una imagen del “antes” con las columnas que se comparan cuando se busca la fila que se actualizará y una imagen del “después” que contiene los cambios. Por ejemplo, para el cambio de UPDATE-DELETE, UPDATE-DELETE es la imagen del "antes" y UPDATE-INSERT es la imagen del "después". Obtén más información sobre la replicación basada en filas de PostgreSQL.
PostgreSQL	tx_id	string	string	El ID de transacción al que pertenece el evento.
PostgreSQL	lsn	string	string	El número de secuencia de 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	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	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	El número de secuencia de 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	Arreglo de strings	Arreglo de strings	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	El tipo de cambio (“INSERT”, UPDATE, “DELETE”) que representa el evento.

Ejemplo de un flujo de eventos

En este flujo, se ilustran 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.

Nota: Este flujo de eventos de muestra es para una base de datos de Oracle, pero es similar para una base de datos MySQL o PostgreSQL.

TIEMPO	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 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": "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 del momento en que 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.

Origen	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 por 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 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 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 progresivamente 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 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 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 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 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 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 entregarán 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 operaciones de lenguaje de manipulación de datos (DML) “invertidas”. 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

Para obtener más información sobre estos estados, incluida la forma en que se usan en el ciclo de vida de una transmisión, consulta Ciclo de vida de la transmisión.

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.