Neste documento, você encontra uma visão geral de uma assinatura do BigQuery, do fluxo de trabalho e das propriedades associadas a ela.
Uma assinatura do BigQuery é um tipo de assinatura de exportação que grava mensagens em uma tabela atual do BigQuery à medida que elas 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 de executar um job do Dataflow não é necessária quando as mensagens não exigem processamento extra antes de armazená-las 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 que os dados sejam 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 Transmitir do Pub/Sub para o BigQuery.
A assinatura do Pub/Sub para o modelo do BigQuery do Dataflow aplica exatamente uma entrega por padrão. Geralmente, isso é possível por meio de mecanismos de eliminação de duplicação no pipeline do Dataflow. No entanto, a assinatura do BigQuery só aceita entrega pelo menos uma vez. Se a eliminação de duplicação exata for essencial para seu caso de uso, considere processos downstream no BigQuery para lidar com possíveis duplicatas.
Antes de começar
Antes de ler este documento, você precisa conhecer bem:
Como o Pub/Sub funciona e os diferentes termos do Pub/Sub.
Os diferentes tipos de assinatura compatíveis com o Pub/Sub e os motivos para 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.
Veja a seguir uma breve descrição do fluxo de trabalho que faz referência à Figura 1:
- O Pub/Sub usa a API de gravação de armazenamento do BigQuery para enviar dados para a tabela do BigQuery.
- As mensagens são enviadas em lotes para a tabela do BigQuery.
- Após a conclusão de uma operação de gravação, a API retorna uma resposta OK.
- Se houver falhas na operação de gravação, a própria mensagem do Pub/Sub será confirmada negativamente. Em seguida, a mensagem é reenviada. Se a mensagem falhar muitas vezes e houver um tópico de mensagens inativas configurado na assinatura, ela 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 as propriedades do BigQuery.
Compatibilidade do esquema
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 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.
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
eBYTEINT
são aliases deINTEGER
,DECIMAL
é um alias deNUMERIC
eBIGDECIMAL
é um alias deBIGNUMERIC
.Quando o tipo no esquema de tópicos é
string
e o tipo na tabela do BigQuery éJSON
,TIMESTAMP
,DATETIME
,DATE
,TIME
,NUMERIC
ouBIGNUMERIC
, qualquer valor para esse 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 em que eles anotam, 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 de 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 outro Type |
NULLABLE Type |
outros union s |
Não mapeá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 |
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 números inteiros 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, 1o de janeiro de 1970 |
DATETIME |
Data e 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 Unix, 1o 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
estão definidos como true
nas propriedades da assinatura. Para usar o recurso com
use_topic_schema
, defina o esquema do tópico com o
seguinte campo:
_CHANGE_TYPE
(obrigatório): um campostring
definido comoUPSERT
ouDELETE
.Se uma mensagem do Pub/Sub gravada na tabela do BigQuery tiver
_CHANGE_TYPE
definido comoUPSERT
, o BigQuery atualizará a linha com a mesma chave, se ela existir, ou inserirá uma nova linha.Se uma mensagem do Pub/Sub gravada na tabela do BigQuery tiver
_CHANGE_TYPE
definido comoDELETE
, o BigQuery excluirá a linha na tabela com a mesma chave, se houver.
Para usar o recurso com use_table_schema
, inclua o campo anterior 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.
Lidar com 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
que explica por que
a mensagem do Pub/Sub não foi gravada no
BigQuery.
Cotas e limites
Há limitações de cota na capacidade de processamento de assinantes 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 só consomem a cota de capacidade da API Storage Write. Ignore as outras considerações de cota da API Storage Write nesta instância.
Preços
Para ver 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.
Solucione 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 as APIs REST.