Assinaturas do BigQuery

Este documento fornece uma visão geral de uma assinatura do BigQuery, do fluxo de trabalho e das 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 Trusted Cloud console, 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 lê mensagens e as grava em uma tabela do BigQuery. A sobrecarga de executar 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, é possível usar 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.

O modelo de assinatura do Pub/Sub para BigQuery do Dataflow impõe 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 só aceita a entrega pelo menos uma vez. Se a deduplicação exata for essencial para seu caso de uso, considere processos downstream no BigQuery para lidar com possíveis duplicidades.

Antes de começar

Antes de ler este documento, confira se você conhece os seguintes conceitos:

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

• Os diferentes tipos de assinaturas que o Pub/Sub aceita 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.

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 mensagem do Pub/Sub será confirmada negativamente. A mensagem é enviada novamente. Se a mensagem falhar várias vezes e houver um tópico de mensagens inativas configurado na assinatura, ela será movida para esse tópico.

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

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 de 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 uma variedade de formatos.

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

• As mensagens que contêm um campo formatado incorretamente não são gravadas 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ópico é string e o tipo na tabela do BigQuery é JSON, TIMESTAMP, DATETIME, DATE, TIME, NUMERIC ou BIGNUMERIC, qualquer valor para esse 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.

A seguir, há uma coleção de mapeamentos de diferentes formatos de esquema para tipos de dados do BigQuery.

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. Confira 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, 1º de janeiro de 1970
DATETIME	A data e a hora em microssegundos expressas como hora 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 vai excluir a linha na tabela com a mesma chave, se ela existir.

• _CHANGE_SEQUENCE_NUMBER (opcional): um campo string 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. 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 da tabela do BigQuery. O número de sequência precisa seguir o formato _CHANGE_SEQUENCE_NUMBER.

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

Para informações sobre os preços da CDC, consulte Preços da CDC.

Tabelas do BigLake para Apache Iceberg no BigQuery

As assinaturas do BigQuery podem ser usadas com tabelas do BigLake para Apache Iceberg no BigQuery sem necessidade de outras mudanças.

As tabelas do BigLake para Apache Iceberg no BigQuery fornecem a base para criar lakehouses de formato aberto no Trusted Cloud by S3NS. Essas tabelas oferecem a mesma experiência totalmente gerenciada das tabelas padrão (integradas) do BigQuery, mas armazenam dados em buckets de armazenamento de propriedade do cliente usando o Parquet para serem interoperáveis com formatos de tabela aberta do Iceberg.

Para informações sobre como criar tabelas do BigLake para o Apache Iceberg no BigQuery , consulte Criar uma tabela do Iceberg.

Lidar com falhas nas 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 reduzir a entrega de mensagens de maneira semelhante ao comportamento de redução de push. No entanto, se a assinatura tiver um tópico de mensagens inativas anexado, o Pub/Sub não vai reduzir a entrega quando as falhas de mensagem forem devido a erros de compatibilidade de esquema.

Cotas e limites

Há limitações de cota no throughput de 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 capacidade de processamento 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

• Crie uma assinatura, como uma assinatura do BigQuery.

• Resolver problemas de uma assinatura do BigQuery.

• Leia sobre o BigQuery.

• Revise os preços do Pub/Sub, incluindo assinaturas do BigQuery.

• Crie ou modifique uma assinatura com os comandos da CLI gcloud.

• Crie ou modifique uma assinatura com APIs REST.