Assinaturas do BigQuery

Neste documento, apresentamos uma visão geral de uma assinatura do BigQuery, o fluxo de trabalho dela e as propriedades associadas.

Uma assinatura do BigQuery é um tipo de assinatura de exportação que grava mensagens em uma tabela do BigQuery à medida que são recebidas. Você não precisa 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, remover 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 lê mensagens e as grava em uma tabela do BigQuery. A sobrecarga da execução de um job do Dataflow não é necessária quando as mensagens não exigem processamento adicional antes de serem armazenadas em uma tabela do BigQuery. Em vez disso, use uma assinatura do BigQuery.

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

A assinatura do Pub/Sub para o modelo do BigQuery do Dataflow é aplicada exatamente uma vez por padrão. Isso geralmente é feito por meio de mecanismos de eliminação de duplicação no pipeline do Dataflow. No entanto, a assinatura do BigQuery só aceita pelo menos uma entrega. Se a eliminação de duplicação exata for essencial para seu caso de uso, considere os processos downstream no BigQuery para lidar com possíveis duplicatas.

Antes de começar

Antes de ler este documento, certifique-se de que você conheça o seguinte:

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 para uma assinatura do BigQuery

Aqui está uma breve descrição do fluxo de trabalho que referencia a Figura 1:

  1. O Pub/Sub usa a API de gravação de armazenamento do BigQuery para enviar dados para a 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á reconhecida negativamente. A mensagem é reenviada. Se a mensagem falhar muitas 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 configuradas 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 de esquema

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 buffer de protocolo, enquanto os esquemas do BigQuery são definidos usando vários formatos. Veja a seguir uma lista de informações importantes sobre a compatibilidade de esquema entre um tópico do Pub/Sub e uma tabela do BigQuery.

  • Qualquer mensagem que contenha um campo formatado incorretamente não será 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 de tópicos é 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 aderir ao formato especificado para o tipo de dados do BigQuery.

  • Alguns tipos lógicos Avro são compatíveis, conforme especificado na tabela a seguir. Todos os tipos lógicos não listados correspondem apenas ao tipo Avro equivalente que eles anotam, conforme detalhado na especificação Avro.

Veja a seguir uma coleção de mapeamentos de diferentes formatos de esquema para os 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 o 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 Inmapeável
fixed BYTES, NUMERIC ou BIGNUMERIC
enum INTEGER

Tipos lógicos Avro

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

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 Inmapeável
map<KeyType, ValueType> REPEATED RECORD<key KeyType, value ValueType>
enum INTEGER
repeated/array of Type REPEATED Type

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

Ao mapear de um número inteiro para um dos tipos de data ou hora, o número precisa representar o valor correto. Veja a seguir 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, 1o de janeiro de 1970
DATETIME A data e a hora em microssegundos expressas como hora civil usando o CivilTimeEncoder
TIME A hora em microssegundos expressa como hora civil usando o CivilTimeEncoder
TIMESTAMP O número de microssegundos desde a época Unix, 1o de janeiro de 1970 00:00:00 UTC

Captura de dados alterados do BigQuery

As assinaturas do BigQuery são compatíveis com atualizações de captura de dados de alterações (CDC, na sigla em inglês) quando use_topic_schema ou use_table_schema está 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 atualizará a linha com a mesma chave, se existir, ou inserirá uma nova linha, caso não exista.

    • 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 houver.

  • _CHANGE_SEQUENCE_NUMBER (opcional): um campo int64 (long) ou int32 (int) definido para garantir que as atualizações e exclusões feitas na tabela do BigQuery sejam processadas em ordem. As mensagens para a mesma chave de linha precisam conter um valor monotonicamente crescente para _CHANGE_SEQUENCE_NUMBER. As mensagens com números de sequência menores que o maior número de sequência processada para uma linha não afetam a linha na tabela do 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 da tabela. Para mais informações, consulte Atribuir papéis do BigQuery à conta de serviço do Pub/Sub.

Gerenciar falhas de mensagens

Quando não é possível gravar uma mensagem do Pub/Sub no BigQuery, ela não pode ser confirmada. Para encaminhar essas mensagens que não podem ser 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 que tem o motivo para a mensagem do Pub/Sub não ser gravada no BigQuery.

Cotas e limites

Há limitações de cota na capacidade de processamento 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 Storage Write do BigQuery. As assinaturas do BigQuery só consomem a cota de capacidade da API Storage Write. Ignore as outras considerações sobre a cota da API Storage Write nesta instância.

Preços

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

A seguir