Abbonamenti BigQuery

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.

Flusso di messaggi per una sottoscrizione BigQuery
Figura 1. Flusso di lavoro per una sottoscrizione BigQuery

Ecco una breve descrizione del flusso di lavoro che fa riferimento alla Figura 1:

  1. Pub/Sub utilizza l'API BigQuery Storage Writer per inviare dati alla tabella BigQuery.
  2. I messaggi vengono inviati in batch alla tabella BigQuery.
  3. Dopo il completamento di un'operazione di scrittura, l'API restituisce una risposta OK.
  4. 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 e BYTEINT sono alias per INTEGER; DECIMAL è un alias di NUMERIC e BIGDECIMAL è un alias di BIGNUMERIC.

  • Se il tipo nello schema dell'argomento è string e il tipo nella tabella BigQuery è JSON, TIMESTAMP, DATETIME, DATE, TIME, NUMERIC o BIGNUMERIC, 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 campo string impostato su UPSERT o DELETE.

    • Se in un messaggio Pub/Sub scritto nella tabella BigQuery _CHANGE_TYPE è impostato su UPSERT, 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 su DELETE, 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.

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