Eventos e transmissões

Visão geral

A hierarquia de dados no Datastream é:

  • Um stream, que é composto por uma origem de dados e um destino.
  • Um objeto, que é uma parte de um fluxo, como uma tabela de um banco de dados específico.
  • Um evento, que é uma única alteração gerada por um objeto específico, como uma inserção de banco de dados.

Streams, objetos e eventos têm dados e metadados associados a eles. Esses dados e metadados podem ser usados para diferentes finalidades.

Sobre eventos

Cada evento consiste em três tipos de dados:

  • Dados do evento: representa a alteração nos dados do objeto originado na origem do stream. Cada evento contém toda a linha que foi alterada.
  • Metadados genéricos: aparecem em todos os eventos gerados pelo Datastream que são usados para ações, como a remoção de dados duplicados no destino.
  • Metadados específicos de origem: esses metadados aparecem em todos os eventos gerados por uma origem de stream específica. Esses metadados variam de acordo com a origem.

Dados do evento

Os dados do evento são o payload de todas as alterações de um determinado objeto originados em uma origem de stream.

Os eventos estão no formato Avro ou JSON.

Ao trabalhar com o formato Avro, o evento contém o índice e o valor de cada coluna. Usando o índice da coluna, o nome da coluna e o tipo unificado podem ser recuperados do esquema no cabeçalho Avro.

Ao trabalhar com o formato JSON, o evento contém o nome e o valor de cada coluna.

Os metadados do evento podem ser usados para coletar informações sobre a origem do evento, bem como remover dados duplicados no destino e ordenar os eventos pelo consumidor downstream.

As tabelas a seguir listam e descrevem os campos e tipos de dados para metadados de evento genéricos e específicos da origem.

Metadados genéricos

Esses metadados são consistentes em streams de todos os tipos.

Campo Tipo Avro Tipo de JSON Descrição
stream_name string string Nome exclusivo do stream, conforme definido no momento da criação.
read_method string string

Indica se os dados foram lidos da origem usando um método de captura de dados de alteração (CDC, na sigla em inglês), como parte do preenchimento histórico ou como parte de uma tarefa de suplemento criada quando uma transação é revertida durante a replicação do CDC.

Os valores possíveis incluem:

  • oracle-cdc-logminer
  • oracle-backfill
  • oracle-supplementation
  • mysql-cdc-binlog
  • mysql-backfill-incremental
  • mysql-backfill-fulldump
  • postgres-cdc-wal
  • postgresql-backfill
object string string O nome usado para agrupar diferentes tipos de eventos, normalmente o nome da tabela ou do objeto na origem.
schema_key string string Identificador exclusivo do esquema unificado do evento.
uuid string string Um identificador exclusivo do evento gerado pelo Datastream.
read_timestamp timestamp-millis string O carimbo de data/hora (UTC) em que o registro foi lido pelo Datastream (o carimbo de data/hora da época em milissegundos).
source_timestamp timestamp-millis string O carimbo de data/hora (UTC) em que o registro foi alterado na origem (o carimbo de data/hora da época em milissegundos).
sort_keys {"type": "array", "items": ["string", "long"]} matriz Matriz de valores que pode ser usada para classificar eventos na ordem em que ocorreram.

Metadados específicos da origem

Esses metadados são associados a eventos de preenchimento e CDC de um banco de dados de origem. Para visualizar esses metadados, selecione uma origem no menu suspenso abaixo.

Origem Campo Tipo Avro Tipo de JSON Descrição
MySQL log_file string string O arquivo de registros do Datastream que extrai eventos na replicação do CDC.
MySQL log_position long long A posição do registro (deslocamento) no registro binário do MySQL.
MySQL primary_keys matriz de strings matriz de strings A lista de um ou mais nomes de colunas que compõem a chave primária das tabelas. Se a tabela não tiver uma chave primária, esse campo estará vazio.
MySQL is_deleted boolean boolean
  • Um valor true indica que a linha foi excluída na origem.
  • O valor false indica que a linha não foi excluída.
MySQL database string string O banco de dados associado ao evento.
MySQL table string string Tabela associada ao evento.
MySQL change_type string string

É o tipo de mudança (INSERT, UPDATE-INSERT, UPDATE-DELETE e DELETE) que o evento representa.

Oracle log_file string string O arquivo de registros do Datastream que extrai eventos na replicação do CDC.
Oracle scn long long A posição do registro (deslocamento) no registro de transações da Oracle.
Oracle row_id string string row_id da Oracle.
Oracle is_deleted boolean boolean
  • Um valor true indica que a linha foi excluída na origem.
  • O valor false indica que a linha não foi excluída.
Oracle database string string O banco de dados associado ao evento.
Oracle schema string string O esquema associado à tabela do evento.
Oracle table string string Tabela associada ao evento.
Oracle change_type string string

É o tipo de mudança (INSERT, UPDATE-INSERT, UPDATE-DELETE e DELETE) que o evento representa.

Oracle tx_id string string É o ID da transação a que o evento pertence.
Oracle rs_id string string O ID do conjunto de registros. A união de rs_id com ssn identifica exclusivamente uma linha em V$LOGMNR_CONTENTS. rs_id identifica exclusivamente o registro redo que gerou a linha.
Oracle ssn long long Um número de sequência SQL. Esse número é usado com rs_id e identifica exclusivamente uma linha em V$LOGMNR_CONTENTS.
PostgreSQL schema string string O esquema associado à tabela do evento.
PostgreSQL table string string Tabela associada ao evento.
PostgreSQL is_deleted booleano boolean
  • Um valor true indica que a linha foi excluída na origem.
  • O valor false indica que a linha não foi excluída.
PostgreSQL change_type string string É o tipo de mudança (INSERT, UPDATE, DELETE) que o evento representa.
PostgreSQL tx_id string string É o ID da transação a que o evento pertence.
PostgreSQL lsn string string O número de sequência do registro da entrada atual.
PostgreSQL primary_keys matriz de strings matriz de strings A lista de um ou mais nomes de colunas que compõem a chave primária das tabelas. Se a tabela não tiver uma chave primária, esse campo estará vazio.
SQL Server table string string Tabela associada ao evento.
SQL Server database long long O banco de dados associado ao evento.
SQL Server schema matriz de strings matriz de strings O esquema associado à tabela do evento.
SQL Server is_deleted booleano booleano
  • Um valor verdadeiro indica que a linha foi excluída na origem.
  • Um valor falso significa que a linha não foi excluída.
SQL Server lsn string string O número de sequência do registro do evento.
SQL Server tx_id string string É o ID da transação a que o evento pertence.
SQL Server physical_location Matriz de números inteiros Matriz de números inteiros O local físico do registro de log descrito por três números inteiros: ID do arquivo, ID da página e ID do slot do registro.
SQL Server replication_index Matriz de strings Matriz de strings A lista de nomes de colunas de um índice que pode identificar exclusivamente uma linha na tabela.
SQL Server change_type String String

O tipo de mudança (INSERT, UPDATE, DELETE) que o evento representa.

Exemplo de um fluxo de eventos

Esse fluxo ilustra os eventos gerados por três operações consecutivas: INSERT, UPDATE e DELETE, em uma única linha em uma tabela SAMPLE de um banco de dados de origem.

TIME THIS_IS_MY_PK (int) FIELD1 (nchar anulável) FIELD2 (nchar não nulo)>
0 1231535353 foo TLV
1 1231535353 NULL TLV

INSERIR (T0)

O payload da mensagem consiste em toda a nova linha.

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

ATUALIZAR (T1)

O payload da mensagem consiste em toda a nova linha. Ele não inclui 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",
  }
}

EXCLUIR (T2)

O payload da mensagem consiste em toda a nova linha.

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

Ordem e consistência

Nesta seção, abordamos como o Datastream lida com a ordem e a consistência.

Pedidos

O Datastream não garante a ordem, mas cada evento contém a linha completa de dados e o carimbo de data/hora de quando os dados foram gravados na origem. No BigQuery, os eventos fora de ordem são automaticamente mesclados na sequência correta. O BigQuery usa os metadados de evento e um número de sequência de alteração (CSN, na sigla em inglês) interno para aplicar os eventos à tabela na ordem correta. No Cloud Storage, os eventos do mesmo período podem abranger mais de um arquivo.

Os eventos gerados fora de ordem ocorrem por padrão quando os eventos são preenchidos para o preenchimento inicial dos dados criados quando o stream é iniciado.

A ordenação pode ser inferida por fonte.

Origem Descrição
MySQL

Os eventos que fazem parte do preenchimento inicial têm o campo read_method começando com mysql-backfill. Não há implicação na ordem em que os eventos são recebidos no preenchimento, pois podem ser consumidos em qualquer ordem.

Os eventos que fazem parte da replicação contínua têm o campo read_method definido como mysql-cdc-binlog.

A ordem pode ser inferida pela combinação do campo log_file e do campo log_position que está separado do arquivo de registros. Essa combinação fornece um número único e crescente que identifica a ordem de operação no banco de dados.

Oracle

Os eventos que fazem parte do preenchimento inicial têm o campo read_method começando com oracle-backfill. Não há implicação na ordem em que os eventos são recebidos no preenchimento, pois podem ser consumidos em qualquer ordem.

Os eventos que fazem parte da replicação contínua têm o campo read_method definido como oracle-cdc-logminer.

A ordem pode ser inferida pela combinação do campo rs_id (o ID do conjunto de registros) e do campo ssn (um número de sequência do SQL). Essa combinação fornece um número único e crescente que identifica a ordem de operação no banco de dados.

PostgreSQL

Os eventos que fazem parte do preenchimento inicial têm o campo read_method começando com postgresql-backfill. Não há implicação na ordem em que os eventos são recebidos no preenchimento, pois podem ser consumidos em qualquer ordem.

Os eventos que fazem parte da replicação contínua têm o campo read_method definido como postgres-cdc-wal.

A ordem pode ser inferida pela combinação do campo source_timestamp e do campo lsn (número de sequência do registro). Essa combinação fornece um número único e crescente que identifica a ordem de operação no banco de dados.

SQL Server

Os eventos que fazem parte do preenchimento inicial têm o campo read_method começando com sqlserver-backfill. Não há implicação na ordem em que os eventos são recebidos no preenchimento, pois podem ser consumidos em qualquer ordem.

Os eventos que fazem parte da replicação contínua têm o campo read_method definido como sqlserver-cdc.

A ordem pode ser inferida pela combinação do campo source_timestamp e do campo lsn (número de sequência de registro). Essa combinação fornece um número único e crescente que identifica a ordem de operação no banco de dados.

Consistência

O Datastream garante que as informações do banco de dados de origem sejam entregues ao destino pelo menos uma vez. Nenhum evento será perdido, mas há uma possibilidade de eventos duplicados no stream. A janela de eventos duplicados deve estar na ordem de minutos, e o identificador universal exclusivo (UUID, na sigla em inglês) do evento nos metadados do evento pode ser usado para detectar duplicações.

Quando os arquivos de registros do banco de dados contêm transações não confirmadas, se alguma transação for revertida, isso refletirá isso nos arquivos de registros como operações de linguagem de manipulação de dados (DML) "reversa". Por exemplo, uma operação INSERT revertida terá uma operação DELETE correspondente. O Datastream lê essas operações dos arquivos de registros.

Sobre os streams

Todo stream tem metadados que descrevem o stream e a origem da qual ele extrai os dados. Esses metadados incluem informações como o nome do stream, os perfis de conexão de origem e de destino etc.

Para ver a definição completa do objeto Stream, consulte a documentação Referência da API.

Estado e status do stream

Um stream pode estar em um dos seguintes estados:

  • Not started
  • Starting
  • Running
  • Draining
  • Paused
  • Failed
  • Failed permanently

É possível usar os registros para encontrar informações de status adicionais, como preenchimento de tabelas, número de linhas processadas etc. Também é possível usar a API FetchStreamErrors para recuperar erros.

Metadados de objeto disponíveis usando a API de descoberta

A API Discover retorna objetos que representam a estrutura dos objetos definidos na fonte ou no destino de dados representado pelo perfil de conexão. Cada objeto tem metadados sobre o objeto em si, bem como para cada campo de dados que extrai. Esses metadados estão disponíveis por meio da API Discover.

A seguir