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.

Observação: quando o Datastream converte dados para o formato Avro, os caracteres especiais nos nomes das colunas são substituídos por sublinhados. Isso pode levar à duplicação dos nomes das colunas e à falha dos streams. Para mais informações sobre convenções de nomenclatura no Avro, consulte a documentação do Apache Avro (em inglês).

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.

Todas as origens MySQL Oracle PostgreSQL SQL Server

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. Para a replicação baseada em linha do MySQL, cada evento para uma linha com uma alteração de chave primária contém duas imagens: uma imagem "antes" cujas colunas são correspondidas ao pesquisar a linha a ser atualizada, e uma imagem "Depois" contendo as alterações. Por exemplo, para a mudança UPDATE-DELETE, UPDATE-DELETE é a imagem "antes" e UPDATE-INSERT é a imagem "depois". Saiba mais sobre replicação baseada em linha do MySQL (em inglês).
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. Para a replicação baseada em linha do Oracle, cada evento para uma linha com uma alteração de chave primária contém duas imagens: uma imagem "antes" em que as colunas são correspondidas ao pesquisar a linha a ser atualizada, e uma imagem "depois" contendo as alterações. Por exemplo, para a mudança UPDATE-DELETE, UPDATE-DELETE é a imagem "antes" e UPDATE-INSERT é a imagem "depois". Saiba mais sobre a replicação baseada em linha do Oracle.
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. Para a replicação baseada em linhas do PostgreSQL, cada evento de uma linha com uma alteração de chave primária contém duas imagens: uma "antes" imagem cujas colunas são correspondidas ao pesquisar a linha a ser atualizada, e uma imagem "depois" imagem que contém as alterações. Por exemplo, para a mudança UPDATE-DELETE, UPDATE-DELETE é o prefixo "antes" e UPDATE-INSERT é o "depois" imagem. Saiba mais sobre replicação baseada em linhas do PostgreSQL.
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.

Observação: este fluxo de eventos de amostra é para um banco de dados Oracle, mas é semelhante a um banco de dados MySQL ou PostgreSQL.

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

Para mais informações sobre esses estados, incluindo como eles são usados, consulte Ciclo de vida da transmissão.

É 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

• Para saber mais sobre transmissões, consulte Ciclo de vida de transmissões.
• Para aprender a criar uma transmissão, consulte Criar uma transmissão.