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:
Como o Pub/Sub funciona e os diferentes termos.
Os diferentes tipos de assinaturas compatíveis com o Pub/Sub e por que 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.
Aqui está uma breve descrição do fluxo de trabalho que referencia a 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á 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
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 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 union s |
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 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 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 comoDELETE
, o BigQuery excluirá a linha na tabela com a mesma chave, se houver.
_CHANGE_SEQUENCE_NUMBER
(opcional): um campoint64
(long
) ouint32
(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
Crie uma assinatura, como uma assinatura do BigQuery.
Resolva problemas de uma assinatura do BigQuery.
Leia sobre o BigQuery.
Revise os preços do Pub/Sub, incluindo as assinaturas do BigQuery.
Crie ou modifique uma assinatura com os comandos da CLI
gcloud
.Crie ou modifique uma assinatura com APIs REST.