Assinaturas do BigQuery

Este documento fornece uma visão geral de uma assinatura do BigQuery, o fluxo de trabalho e as propriedades associadas.

Uma assinatura do BigQuery é um tipo de assinatura de exportação que grava mensagens em uma tabela do BigQuery conforme elas são recebidas. Não é necessário configurar um cliente assinante separado. Use o console do Google Cloud, a Google Cloud CLI, as bibliotecas de cliente ou a API Pub/Sub para criar, atualizar, listar, desconectar ou excluir uma assinatura do BigQuery.

Sem o tipo de assinatura do BigQuery, você precisa de uma assinatura de pull ou push e de um assinante (como o Dataflow) que leia mensagens e as gravasse em uma tabela do BigQuery. O overhead de executar um job do Dataflow não é necessário quando as mensagens não exigem processamento adicional antes de serem armazenadas em uma tabela do BigQuery. Nesse caso, use uma assinatura do BigQuery.

No entanto, um pipeline do Dataflow ainda é recomendado para sistemas do Pub/Sub em que alguma transformação de dados é necessária antes de serem armazenados em uma tabela do BigQuery. Para saber como transmitir dados do Pub/Sub para o BigQuery com transformação usando o Dataflow, consulte "Transmitir do Pub/Sub para o BigQuery".

A assinatura do Pub/Sub para o modelo do BigQuery do Dataflow aplica a entrega exatamente uma vez por padrão. Isso geralmente é feito com mecanismos de eliminação de duplicação no pipeline do Dataflow. No entanto, a assinatura do BigQuery oferece suporte apenas para pelo menos uma entrega. Se a deduplicação exata for essencial para seu caso de uso, considere usar processos downstream no BigQuery para processar possíveis duplicações.

Antes de começar

Antes de ler este documento, confira se você conhece os seguintes tópicos:

  • Como o Pub/Sub funciona e os diferentes termos do Pub/Sub.

  • Os diferentes tipos de assinaturas com suporte do Pub/Sub e por que você pode querer usar uma assinatura do BigQuery.

  • Como o BigQuery funciona e como configurar e gerenciar tabelas do BigQuery.

Fluxo de trabalho de assinatura do BigQuery

A imagem a seguir mostra o fluxo de trabalho entre uma assinatura do BigQuery e o BigQuery.

Fluxo de mensagens para uma assinatura do BigQuery
Figura 1. Fluxo de trabalho de uma assinatura do BigQuery

Confira uma breve descrição do fluxo de trabalho que faz referência à Figura 1:

  1. O Pub/Sub usa a API BigQuery Storage Write para enviar dados à tabela do BigQuery.
  2. As mensagens são enviadas em lotes para a tabela do BigQuery.
  3. Após a conclusão de uma operação de gravação, a API retorna uma resposta OK.
  4. Se houver falhas na operação de gravação, a própria mensagem do Pub/Sub será confirmada negativamente. A mensagem é reenviada. Se a mensagem falhar várias vezes e houver um tópico de mensagens inativas configurado na assinatura, a mensagem será movida para o tópico de mensagens inativas.

Propriedades de uma assinatura do BigQuery

As propriedades que você configura para uma assinatura do BigQuery determinam a tabela do BigQuery em que o Pub/Sub grava mensagens e o tipo de esquema dessa tabela.

Para mais informações, consulte Propriedades do BigQuery.

Compatibilidade do esquema

Esta seção só é aplicável se você selecionar a opção Usar esquema de tópicos ao criar uma assinatura do BigQuery.

O Pub/Sub e o BigQuery usam maneiras diferentes para definir os esquemas. Os esquemas do Pub/Sub são definidos no formato Apache Avro ou Protocol Buffer, enquanto os esquemas do BigQuery são definidos usando uma variedade de formatos.

Confira a seguir uma lista de informações importantes sobre a compatibilidade do esquema entre um tópico do Pub/Sub e uma tabela do BigQuery.

  • Qualquer mensagem que contenha um campo formatado incorretamente não é gravada no BigQuery.

  • No esquema do BigQuery, INT, SMALLINT, INTEGER, BIGINT, TINYINT e BYTEINT são aliases de INTEGER; DECIMAL é um alias de NUMERIC; e BIGDECIMAL é um alias de BIGNUMERIC.

  • Quando o tipo no esquema do tópico é string e o tipo na tabela do BigQuery é JSON, TIMESTAMP, DATETIME, DATE, TIME, NUMERIC ou BIGNUMERIC, qualquer valor desse campo em uma mensagem do Pub/Sub precisa obedecer ao formato especificado para o tipo de dados do BigQuery.

  • Alguns tipos lógicos do Avro são aceitos, conforme especificado na tabela a seguir. Qualquer tipo lógico não listado corresponde apenas ao tipo Avro equivalente que ele anota, conforme detalhado na especificação do Avro.

Confira a seguir uma coleção de mapeamentos de diferentes formatos de esquema para tipos de dados do BigQuery.

Tipos Avro

Tipo Avro Tipo de dados do BigQuery
null Any NULLABLE
boolean BOOLEAN
int INTEGER, NUMERIC ou BIGNUMERIC
long INTEGER, NUMERIC ou BIGNUMERIC
float FLOAT64, NUMERIC ou BIGNUMERIC
double FLOAT64, NUMERIC ou BIGNUMERIC
bytes BYTES, NUMERIC ou BIGNUMERIC
string STRING, JSON, TIMESTAMP, DATETIME, DATE, TIME, NUMERIC ou BIGNUMERIC
record RECORD/STRUCT
array de Type REPEATED Type
map com tipo de valor ValueType REPEATED STRUCT <key STRING, value ValueType>
union com dois tipos, um que é null e o outro Type NULLABLE Type
outros unions Não mapeável
fixed BYTES, NUMERIC ou BIGNUMERIC
enum INTEGER

Tipos lógicos do Avro

Tipo lógico Avro Tipo de dados do BigQuery
timestamp-micros TIMESTAMP
date DATE
time-micros TIME
duration INTERVAL
decimal NUMERIC ou BIGNUMERIC

Tipos de buffer de protocolo

Tipo de buffer de protocolo Tipo de dados do BigQuery
double FLOAT64, NUMERIC ou BIGNUMERIC
float FLOAT64, NUMERIC ou BIGNUMERIC
int32 INTEGER, NUMERIC, BIGNUMERIC ou DATE
int64 INTEGER, NUMERIC, BIGNUMERIC, DATE, DATETIME ou TIMESTAMP
uint32 INTEGER, NUMERIC, BIGNUMERIC ou DATE
uint64 NUMERIC ou BIGNUMERIC
sint32 INTEGER, NUMERIC ou BIGNUMERIC
sint64 INTEGER, NUMERIC, BIGNUMERIC, DATE, DATETIME ou TIMESTAMP
fixed32 INTEGER, NUMERIC, BIGNUMERIC ou DATE
fixed64 NUMERIC ou BIGNUMERIC
sfixed32 INTEGER, NUMERIC, BIGNUMERIC ou DATE
sfixed64 INTEGER, NUMERIC, BIGNUMERIC, DATE, DATETIME ou TIMESTAMP
bool BOOLEAN
string STRING, JSON, TIMESTAMP, DATETIME, DATE, TIME, NUMERIC ou BIGNUMERIC
bytes BYTES, NUMERIC ou BIGNUMERIC
enum INTEGER
message RECORD/STRUCT
oneof Não mapeável
map<KeyType, ValueType> REPEATED RECORD<key KeyType, value ValueType>
enum INTEGER
repeated/array of Type REPEATED Type

Representação de data e hora como número inteiro

Ao mapear um número inteiro para um dos tipos de data ou hora, o número precisa representar o valor correto. Confira abaixo o mapeamento dos tipos de dados do BigQuery para o número inteiro que os representa.

Tipo de dados do BigQuery Representação de números inteiros
DATE O número de dias desde a época Unix, 1º de janeiro de 1970
DATETIME A data e a hora em microssegundos expressas como horário civil usando o CivilTimeEncoder
TIME O tempo em microssegundos expresso como hora civil usando o CivilTimeEncoder
TIMESTAMP O número de microssegundos desde a época do Unix, 1º de janeiro de 1970 00:00:00 UTC

Captura de dados alterados do BigQuery

As assinaturas do BigQuery oferecem suporte a atualizações de captura de dados alterados (CDC) quando use_topic_schema ou use_table_schema é definido como true nas propriedades da assinatura. Para usar o recurso com use_topic_schema, defina o esquema do tópico com os seguintes campos:

  • _CHANGE_TYPE (obrigatório): um campo string definido como UPSERT ou DELETE.

    • Se uma mensagem do Pub/Sub gravada na tabela do BigQuery tiver _CHANGE_TYPE definido como UPSERT, o BigQuery vai atualizar a linha com a mesma chave, se ela existir, ou inserir uma nova linha, se não existir.

    • Se uma mensagem do Pub/Sub gravada na tabela do BigQuery tiver _CHANGE_TYPE definido como DELETE, o BigQuery excluirá a linha na tabela com a mesma chave, se ela existir.

  • _CHANGE_SEQUENCE_NUMBER (opcional): um campo int64 (long) definido para garantir que as atualizações e exclusões feitas na tabela do BigQuery sejam processadas na ordem. As mensagens para a mesma chave de linha precisam conter um valor monotonicamente crescente para _CHANGE_SEQUENCE_NUMBER. Mensagens com números de sequência menores que o maior número de sequência processado para uma linha não têm efeito na linha na tabela do BigQuery. O Pub/Sub exige um valor baseado em números inteiros, em vez do valor baseado em string usado ao interagir diretamente com o BigQuery.

Para usar o recurso com use_table_schema, inclua os campos anteriores na mensagem JSON.

Permissões da conta de serviço do Pub/Sub

Para criar uma assinatura do BigQuery, a conta de serviço do Pub/Sub precisa ter permissão para gravar na tabela específica do BigQuery e ler os metadados dela. Para mais informações, consulte Atribuir papéis do BigQuery à conta de serviço do Pub/Sub.

Processar falhas de mensagens

Quando uma mensagem do Pub/Sub não pode ser gravada no BigQuery, ela não pode ser confirmada. Para encaminhar essas mensagens não entregues, configure um tópico de mensagens inativas na assinatura do BigQuery. A mensagem do Pub/Sub encaminhada para o tópico de mensagens inativas contém um atributo CloudPubSubDeadLetterSourceDeliveryErrorMessage com o motivo pelo qual a mensagem do Pub/Sub não pôde ser gravada no BigQuery.

Se o Pub/Sub não conseguir gravar mensagens no BigQuery, ele vai suspender o envio de mensagens de forma semelhante ao comportamento de push backoff. No entanto, se a assinatura tiver um tópico de mensagens inativas anexado, o Pub/Sub não vai interromper a entrega quando as falhas de mensagem forem devido a erros de compatibilidade do esquema.

Cotas e limites

Há limitações de cota na taxa de transferência do assinante do BigQuery por região. Para mais informações, consulte Cotas e limites do Pub/Sub.

As assinaturas do BigQuery gravam dados usando a API BigQuery Storage Write. Para informações sobre as cotas e os limites da API Storage Write, consulte Solicitações da API BigQuery Storage Write. As assinaturas do BigQuery consomem apenas a cota de throughput da API Storage Write. Você pode ignorar as outras considerações de cota da API Storage Write nesta instância.

Preços

Para saber os preços das assinaturas do BigQuery, consulte a página de preços do Pub/Sub.

A seguir