Eventos e transmissões

O Datastream organiza os dados replicados em uma hierarquia de três níveis de streams, objetos e eventos. Um stream conecta uma fonte de dados a um destino, enquanto um objeto representa uma entidade de origem específica nesse stream, como uma tabela de banco de dados. Um evento captura uma única alteração de dados de um objeto, como uma inserção de banco de dados.

Cada evento inclui dados e metadados que identificam o fluxo e o objeto de origem. É possível usar esses metadados para rastrear as origens das alterações, remover registros duplicados no destino e manter a ordenação entre os consumidores downstream.

Sobre eventos

Cada evento consiste em três tipos de dados:

• Dados de eventos: representam a mudança nos dados do objeto que se origina da fonte do stream. Cada evento contém toda a linha que foi alterada.
• Metadados genéricos: esses metadados aparecem em todos os eventos gerados pelo Datastream que são usados para ações, como remover dados duplicados no destino.
• Metadados específicos da origem: 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, para cada coluna, o evento contém o índice e o valor da 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 a nomes de colunas duplicados e resultar em falhas nas transmissões. Para mais informações sobre convenções de nomenclatura no Avro, consulte a documentação do Apache Avro.

Ao trabalhar com o formato JSON, para cada coluna, o evento contém o nome e o valor da 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 alterados (CDC), como parte do preenchimento histórico ou como parte de uma tarefa de suplementação criada quando uma transação é revertida durante a replicação de CDC. Os valores possíveis incluem: 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	O nome usado para agrupar diferentes tipos de eventos, normalmente o nome da tabela ou do objeto na origem.
schema_key	string	string	Um identificador exclusivo para o 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 conferir esses metadados, selecione uma origem no menu suspenso abaixo.

Todas as fontes MySQL Oracle PostgreSQL SQL Server Spanner Salesforce MongoDB

Origem	Campo	Tipo Avro	Tipo de JSON	Descrição
MySQL	log_file	string	string	O arquivo de registro de onde o Datastream extrai eventos na replicação de CDC ao usar a replicação baseada em binlog.
MySQL	log_position	long	long	A posição do registro (deslocamento) no registro binário do MySQL ao usar a replicação baseada em binlog.
MySQL	binlog_file	string	string	O arquivo de registro binário de onde o Datastream extrai eventos na replicação de CDC ao usar a replicação baseada em GTID.
MySQL	binlog_position	long	long	A posição (deslocamento) no registro binário do MySQL ao usar a replicação baseada em GTID.
MySQL	gtid	string	string	O identificador de transação global (GTID, na sigla em inglês) que identifica exclusivamente a transação do evento ao usar a replicação baseada em GTID.
MySQL	datastream_master_server_uuid	string	string	O UUID da instância do servidor de origem do MySQL de onde o Datastream lê eventos ao usar a replicação baseada em GTID.
MySQL	datastream_master_server_id	long	long	O ID do servidor da instância do servidor de origem do MySQL de onde o Datastream lê eventos ao usar a replicação baseada em GTID.
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 do 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 linha do PostgreSQL, cada evento de uma linha com uma mudança de chave primária contém duas imagens: uma imagem "antes", cujas colunas são comparadas ao pesquisar a linha a ser atualizada, e uma imagem "depois", que contém as mudanças. 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 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 para a 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	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.
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 registro 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.
Spanner	commit_timestamp	timestamp-micros	string	O carimbo de data/hora de confirmação do evento.
Spanner	snapshot	booleano	booleano	Se o evento é um evento de snapshot de preenchimento.
Spanner	project_id	string	string	O identificador do projeto do Spanner.
Spanner	instance_id	string	string	O identificador da instância do Spanner.
Spanner	database_id	string	string	O identificador do banco de dados do Spanner.
Spanner	schema	string	string	O esquema associado à tabela do evento. Vazio se a tabela não estiver em um esquema nomeado.
Spanner	table	string	string	A tabela do Spanner.
Spanner	change_stream_name	string	string	O fluxo de alterações do Spanner.
Spanner	server_transaction_id	string	string	O identificador da transação associado ao evento.
Spanner	record_sequence	long ou string	long ou string	A sequência de registros associada ao evento. Para fluxo de alterações criados com o modo de partição IMMUTABLE_KEY_RANGE, o valor é um número de sequência numérico do tipo long. Para fluxos de alterações criados com o modo de partição MUTABLE_KEY_RANGE, o valor é a string record_sequence do registro de alteração de dados, como 1cac8f3f38eeaf53-00000000.
Spanner	mod_number	long	long	O número da modificação associada ao evento.
Spanner	transaction_tag	string	string	A tag da transação associada.
Spanner	number_of_records_in_transaction	long	long	O número de registros na transação associada.
Spanner	value_capture_type	string	string	O tipo de captura de valor do fluxo de alterações. Os valores possíveis são NEW_ROW e NEW_ROW_AND_OLD_VALUES.
Spanner	change_type	string	string	O tipo de mudança (INSERT, UPDATE ou DELETE) que o evento representa.
Spanner	primary_keys	matriz de strings	matriz de strings	A lista de colunas de chave primária da tabela.
Spanner	is_deleted	booleano	booleano	Se a mudança representa um evento DELETE.
Salesforce	object_name	string	string	O nome do objeto do Salesforce associado ao evento.
Salesforce	domain	string	string	O nome do domínio associado ao evento.
Salesforce	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.
Salesforce	change_type	string	string	O tipo de mudança (INSERT, UPDATE, DELETE) que o evento representa.
Salesforce	primary_keys	matriz de strings	matriz de strings	A lista de 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.
MongoDB	database	string	string	O banco de dados associado ao evento.
MongoDB	collection	string	string	A coleção associada ao evento. As coleções são semelhantes às tabelas em bancos de dados relacionais.
MongoDB	change_type	string	string	O tipo de mudança (CREATE, UPDATE e DELETE) que o evento representa.
MongoDB	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.
MongoDB	primary_keys	matriz de strings	matriz de strings	O campo _id, que atua como a chave primária de cada documento em uma coleção.

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 exemplo de fluxo de eventos é para um banco de dados Oracle, mas é semelhante para 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 ordenação e consistência.

Pedidos

O Datastream não garante a entrega de eventos em ordem, mas cada evento contém a linha completa de dados, o carimbo de data/hora de quando os dados foram gravados na origem e os metadados de ordenação.

Os eventos que fazem parte de um preenchimento inicial têm o campo read_method definido como backfill ou terminando com -backfill, -fulldump ou -incremental. Os eventos de preenchimento são gerados fora de ordem por design e podem ser consumidos em qualquer ordem.

Os eventos que fazem parte da replicação contínua de captura de dados alterados (CDC) têm o campo read_method definido como cdc ou um valor de CDC específico da origem, como mysql-cdc-binlog, oracle-cdc-logminer, postgres-cdc-wal, sqlserver-cdc ou salesforce-cdc. A forma de ordenar eventos de replicação contínua em todas as origens depende do destino:

Destino	Descrição
BigQuery	A forma como os eventos são ordenados no BigQuery depende do modo de gravação configurado para o stream: Modo de gravação de mesclagem: o BigQuery mescla automaticamente os eventos fora de ordem na sequência correta usando os metadados do evento e um número de sequência de alteração (CSN, na sigla em inglês) interno. As tabelas sem uma chave primária são gravadas no modo somente anexação. Modo de gravação somente com adição de dados, incluindo tabelas do Apache Iceberg: o Datastream adiciona eventos de alteração à tabela de destino e preenche a coluna STRUCT datastream_metadata. Para determinar a ordem em que os eventos ocorreram na origem, classifique-os usando o campo datastream_metadata.change_sequence_number ou o campo de matriz datastream_metadata.sort_keys.
Cloud Storage	No Cloud Storage, os eventos do mesmo período podem abranger mais de um arquivo. Para determinar a ordem em que os eventos ocorreram na origem, classifique-os usando o campo de matriz sort_keys nos metadados genéricos.

Consistência

O Datastream garante que os dados do banco de dados de origem sejam entregues ao destino pelo menos uma vez. Nenhum evento é perdido, mas há a possibilidade de eventos duplicados no stream. A janela para eventos duplicados deve ser de minutos, e o identificador universalmente exclusivo (UUID) do evento nos metadados do evento pode ser usado para detectar duplicatas.

No entanto, não use apenas o UUID para eliminar a duplicação de eventos downstream. Se houver uma interrupção no pipeline, o Datastream vai ler novamente o registro de origem do último checkpoint salvo para garantir a entrega. Como o Datastream gera UUIDs dinamicamente quando lê um evento, esse tipo de nova tentativa resulta em novos UUIDs para os mesmos dados de origem. Além disso, durante operações em massa no banco de dados de origem, várias linhas distintas podem compartilhar o mesmo número de sequência de alteração (CSN, na sigla em inglês).

Para eliminar a duplicação de dados de maneira confiável, particione os eventos pelas chaves primárias da tabela de origem e agrupe-os usando o número de sequência de alteração (CSN, na sigla em inglês) (o campo change_sequence_number). Isso garante que as novas tentativas do mesmo evento sejam recolhidas corretamente, preservando as atualizações de linha legitimamente distintas de transações em massa.

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 e os perfis de conexão de origem e destino.

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 no ciclo de vida de um stream, consulte Ciclo de vida do stream.

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

Metadados de objeto disponíveis usando a API de descoberta

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

A seguir

• Para saber mais sobre streams, consulte Ciclo de vida do stream.
• Para saber como criar um stream, consulte Criar um stream.