Questo documento fornisce una panoramica di una sottoscrizione BigQuery, il relativo flusso di lavoro e le proprietà associate.
Una sottoscrizione BigQuery è un tipo di sottoscrizione di esportazione che scrive i messaggi in una tabella BigQuery esistente quando vengono ricevuti. Non è necessario configurare un client sottoscrittore separato. Utilizza la console Google Cloud, Google Cloud CLI, le librerie client o l'API Pub/Sub per creare, aggiornare, elencare, scollegare o eliminare un abbonamento BigQuery.
Senza il tipo di sottoscrizione BigQuery, sono necessari una sottoscrizione pull o push e un sottoscrittore (come Dataflow) che legga i messaggi e li scriva in una tabella BigQuery. L'overhead associato all'esecuzione di un job Dataflow non è necessario se i messaggi non richiedono ulteriori elaborazioni prima di archiviarli in una tabella BigQuery; puoi utilizzare invece una sottoscrizione BigQuery.
Tuttavia, è comunque consigliata una pipeline Dataflow per i sistemi Pub/Sub in cui è necessaria una certa trasformazione dei dati prima che vengano archiviati in una tabella BigQuery. Per informazioni su come trasmettere flussi di dati da Pub/Sub a BigQuery mediante la trasformazione mediante Dataflow, consulta Flusso di dati da Pub/Sub a BigQuery.
La sottoscrizione Pub/Sub al modello BigQuery di Dataflow applica la consegna "exactly-once" per impostazione predefinita. Ciò viene tipicamente ottenuto attraverso meccanismi di deduplicazione all'interno della pipeline Dataflow. Tuttavia, l'abbonamento BigQuery supporta la consegna almeno una volta. Se la deduplicazione esatta è fondamentale per il tuo caso d'uso, valuta i processi downstream in BigQuery per gestire i potenziali duplicati.
Prima di iniziare
Prima di leggere questo documento, assicurati di acquisire familiarità con quanto segue:
Come funziona Pub/Sub e i diversi termini di Pub/Sub.
I diversi tipi di abbonamenti supportati da Pub/Sub e il motivo per cui potresti utilizzare una sottoscrizione BigQuery.
Come funziona BigQuery e come configurare e gestire le tabelle BigQuery.
Flusso di lavoro della sottoscrizione BigQuery
L'immagine seguente mostra il flusso di lavoro tra una sottoscrizione BigQuery e BigQuery.
Ecco una breve descrizione del flusso di lavoro che fa riferimento alla Figura 1:
- Pub/Sub utilizza l'API BigQuery Storage Writer per inviare dati alla tabella BigQuery.
- I messaggi vengono inviati in batch alla tabella BigQuery.
- Dopo il completamento di un'operazione di scrittura, l'API restituisce una risposta OK.
- In caso di errori nell'operazione di scrittura, il messaggio Pub/Sub viene confermato negativamente. Il messaggio viene quindi inviato di nuovo. Se il messaggio restituisce un numero sufficiente di messaggi non recapitabili e nella sottoscrizione è configurato un argomento messaggi non recapitabili, il messaggio viene spostato nell'argomento messaggi non recapitabili.
Proprietà di una sottoscrizione BigQuery
Le proprietà configurate per una sottoscrizione BigQuery determinano la tabella BigQuery in cui Pub/Sub scrive i messaggi e il tipo di schema di quella tabella.
Per ulteriori informazioni, consulta la pagina relativa alle proprietà BigQuery.
Compatibilità schema
Pub/Sub e BigQuery usano diversi modi per definire gli schemi. Gli schemi Pub/Sub sono definiti nel formato Apache Avro o Protocol Buffer, mentre gli schemi BigQuery vengono definiti utilizzando una serie di formati. Di seguito è riportato un elenco di informazioni importanti sulla compatibilità dello schema tra un argomento Pub/Sub e una tabella BigQuery.
I messaggi contenenti un campo non correttamente formattato non vengono scritti in BigQuery.
Nello schema BigQuery,
INT
,SMALLINT
,INTEGER
,BIGINT
,TINYINT
eBYTEINT
sono alias perINTEGER
;DECIMAL
è un alias diNUMERIC
eBIGDECIMAL
è un alias diBIGNUMERIC
.Se il tipo nello schema dell'argomento è
string
e il tipo nella tabella BigQuery èJSON
,TIMESTAMP
,DATETIME
,DATE
,TIME
,NUMERIC
oBIGNUMERIC
, qualsiasi valore per questo campo in un messaggio Pub/Sub deve rispettare il formato specificato per il tipo di dati BigQuery.Sono supportati alcuni tipi logici Avro, come specificato nella tabella seguente. Tutti i tipi logici non elencati corrispondono solo al tipo Avro equivalente che annotano, come descritto nelle specifiche di Avro.
Di seguito è riportata una raccolta di mappatura di diversi formati di schema ai tipi di dati BigQuery.
Tipi di Avro
Tipo di avro | Tipo di dati BigQuery |
null |
Any NULLABLE |
boolean |
BOOLEAN |
int |
INTEGER , NUMERIC o
BIGNUMERIC |
long |
INTEGER , NUMERIC o
BIGNUMERIC |
float |
FLOAT64 , NUMERIC o
BIGNUMERIC |
double |
FLOAT64 , NUMERIC o
BIGNUMERIC |
bytes |
BYTES , NUMERIC o
BIGNUMERIC |
string |
STRING , JSON ,
TIMESTAMP , DATETIME ,
DATE , TIME ,
NUMERIC o BIGNUMERIC |
record |
RECORD/STRUCT |
array di Type |
REPEATED Type |
map con tipo di valore ValueType
|
REPEATED STRUCT <key STRING, value
ValueType> |
union con due tipi, uno
null e l'altro Type |
NULLABLE Type |
altri union |
Non mappabile |
fixed |
BYTES , NUMERIC o
BIGNUMERIC |
enum |
INTEGER |
Tipi logici Avro
Tipo logico Avro | Tipo di dati BigQuery |
timestamp-micros |
TIMESTAMP |
date |
DATE |
time-micros |
TIME |
duration |
INTERVAL |
decimal |
NUMERIC o BIGNUMERIC |
Tipi di buffer di protocollo
Tipo di buffer di protocollo | Tipo di dati BigQuery |
double |
FLOAT64 , NUMERIC o
BIGNUMERIC |
float |
FLOAT64 , NUMERIC o
BIGNUMERIC |
int32 |
INTEGER , NUMERIC ,
BIGNUMERIC o DATE |
int64 |
INTEGER , NUMERIC ,
BIGNUMERIC , DATE ,
DATETIME o TIMESTAMP |
uint32 |
INTEGER , NUMERIC ,
BIGNUMERIC o DATE |
uint64 |
NUMERIC o BIGNUMERIC |
sint32 |
INTEGER , NUMERIC o
BIGNUMERIC |
sint64 |
INTEGER , NUMERIC ,
BIGNUMERIC , DATE ,
DATETIME o TIMESTAMP |
fixed32 |
INTEGER , NUMERIC ,
BIGNUMERIC o DATE |
fixed64 |
NUMERIC o BIGNUMERIC |
sfixed32 |
INTEGER , NUMERIC ,
BIGNUMERIC o DATE |
sfixed64 |
INTEGER , NUMERIC ,
BIGNUMERIC , DATE ,
DATETIME o TIMESTAMP |
bool |
BOOLEAN |
string |
STRING , JSON ,
TIMESTAMP , DATETIME ,
DATE , TIME ,
NUMERIC o BIGNUMERIC |
bytes |
BYTES , NUMERIC o
BIGNUMERIC |
enum |
INTEGER |
message |
RECORD/STRUCT |
oneof |
Non mappabile |
map<KeyType, ValueType> |
REPEATED RECORD<key KeyType, value
ValueType> |
enum |
INTEGER |
repeated/array of Type |
REPEATED Type |
Rappresentazione del numero intero per data e ora
Quando si esegue la mappatura da un numero intero a uno dei tipi di data o ora, il numero deve rappresentare il valore corretto. Di seguito è riportata la mappatura dei tipi di dati BigQuery al numero intero che li rappresenta.
Tipo di dati BigQuery | Rappresentazione dei numeri interi |
DATE |
Il numero di giorni dall'epoca di Unix, 1° gennaio 1970 |
DATETIME |
La data e l'ora in microsecondi espresse come ora civile utilizzando CivilTimeEncoder |
TIME |
Il tempo in microsecondi espresso come ora civile utilizzando CivilTimeEncoder |
TIMESTAMP |
Il numero di microsecondi dall'epoca di Unix, 1° gennaio 1970 00:00:00 UTC |
Change Data Capture (CDC) di BigQuery
Gli abbonamenti BigQuery supportano gli aggiornamenti CDC (Change Data Capture) quando use_topic_schema
o use_table_schema
è impostato su true
nelle proprietà dell'abbonamento. Per utilizzare la funzionalità con use_topic_schema
, imposta lo schema dell'argomento con il seguente campo:
_CHANGE_TYPE
(obbligatorio): un campostring
impostato suUPSERT
oDELETE
.Se in un messaggio Pub/Sub scritto nella tabella BigQuery
_CHANGE_TYPE
è impostato suUPSERT
, BigQuery aggiorna la riga con la stessa chiave se esiste o inserisce una nuova riga in caso contrario.Se in un messaggio Pub/Sub scritto nella tabella BigQuery
_CHANGE_TYPE
è impostato suDELETE
, BigQuery elimina la riga nella tabella con la stessa chiave, se esistente.
Per utilizzare la funzionalità con use_table_schema
, includi il campo precedente nel messaggio JSON.
Autorizzazioni dell'account di servizio Pub/Sub
Per creare una sottoscrizione BigQuery, l'account di servizio Pub/Sub deve disporre dell'autorizzazione per scrivere nella tabella BigQuery specifica e per leggere i metadati della tabella. Per ulteriori informazioni, vedi Assegnare ruoli BigQuery all'account di servizio Pub/Sub.
Gestire gli errori relativi ai messaggi
Quando un messaggio Pub/Sub non può essere scritto in
BigQuery, il messaggio non può essere confermato. Per inoltrare i messaggi non recapitabili, configura un argomento messaggi non recapitabili nella sottoscrizione BigQuery. Il messaggio Pub/Sub inoltrato all'argomento messaggi non recapitabili contiene un attributo CloudPubSubDeadLetterSourceDeliveryErrorMessage
che spiega il motivo per cui non è stato possibile scrivere il messaggio Pub/Sub in BigQuery.
Se Pub/Sub non può scrivere messaggi in BigQuery, Pub/Sub annulla la consegna dei messaggi in modo simile al comportamento di backoff di push. Tuttavia, se alla sottoscrizione è associato un argomento messaggi non recapitabili, Pub/Sub non annulla la consegna quando gli errori dei messaggi sono dovuti a errori di compatibilità dello schema.
Quote e limiti
La velocità effettiva dell'abbonato BigQuery per regione è soggetta a limitazioni. Per maggiori informazioni, consulta Quote e limiti di Pub/Sub.
Le sottoscrizioni BigQuery scrivono dati utilizzando l' API BigQuery Storage Scrivi. Per informazioni sulle quote e sui limiti per l'API StorageWrite, consulta Richieste dell'API BigQuery Storage Scrivi. Le sottoscrizioni BigQuery consumano solo la quota di velocità effettiva per l'API StorageWrite. Puoi ignorare le altre considerazioni sulla quota dell'API Storage Scrivi in questa istanza.
Prezzi
Per i prezzi delle sottoscrizioni BigQuery, consulta la pagina dei prezzi di Pub/Sub.
Passaggi successivi
Crea una sottoscrizione, ad esempio una abbonamento BigQuery.
Risolvi i problemi relativi a un abbonamento BigQuery.
Scopri di più su BigQuery.
Esamina i prezzi di Pub/Sub, inclusi gli abbonamenti a BigQuery.
Crea o modifica una sottoscrizione con i comandi dell'interfaccia a riga di comando di
gcloud
.Creare o modificare un abbonamento con API REST.