Abbonamenti BigQuery

Questo documento fornisce una panoramica di una sottoscrizione BigQuery, del relativo flusso di lavoro e delle proprietà associate.

Una sottoscrizione BigQuery è un tipo di sottoscrizione dell'esportazione che scrive i messaggi in una tabella BigQuery esistente alla ricezione. 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 una sottoscrizione BigQuery.

Senza il tipo di sottoscrizione BigQuery, è necessaria una sottoscrizione pull o push e un sottoscrittore (ad esempio Dataflow) che legga i messaggi e li scriva in una tabella BigQuery. Il sovraccarico dell'esecuzione di un job Dataflow non è necessario quando i messaggi non richiedono un'elaborazione aggiuntiva prima di essere archiviati in una tabella BigQuery. Puoi utilizzare un abbonamento BigQuery.

Tuttavia, è comunque consigliabile utilizzare una pipeline Dataflow per i sistemi Pub/Sub in cui è richiesta una certa trasformazione dei dati prima che vengano archiviati in una tabella BigQuery. Per scoprire come trasmettere i dati da Pub/Sub a BigQuery con trasformazione utilizzando Dataflow, consulta Trasmetti flussi da Pub/Sub a BigQuery.

Il modello di sottoscrizione Pub/Sub a BigQuery da Dataflow applica la consegna esattamente una volta per impostazione predefinita. In genere, questo viene ottenuto tramite meccanismi di deduplica all'interno della pipeline Dataflow. Tuttavia, l'abbonamento BigQuery supporta solo la consegna almeno una volta. Se la deduplica esatta è fondamentale per il tuo caso d'uso, valuta la possibilità di utilizzare le procedure a valle in BigQuery per gestire i potenziali duplicati.

Prima di iniziare

Prima di leggere questo documento, assicurati di conoscere quanto segue:

  • Come funziona Pub/Sub e i diversi termini di Pub/Sub.

  • I diversi tipi di sottoscrizioni supportati da Pub/Sub e perché potresti voler utilizzare una sottoscrizione BigQuery.

  • Come funziona BigQuery e come configurare e gestire le tabelle BigQuery.

Flusso di lavoro delle sottoscrizioni BigQuery

L'immagine seguente mostra il flusso di lavoro tra un abbonamento BigQuery e BigQuery.

Flusso di messaggi per una sottoscrizione BigQuery
Figura 1. Workflow per un abbonamento BigQuery

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

  1. Pub/Sub utilizza l'API di scrittura dello spazio di archiviazione BigQuery per inviare i dati alla tabella BigQuery.
  2. I messaggi vengono inviati in batch alla tabella BigQuery.
  3. Al termine di un'operazione di scrittura, l'API restituisce una risposta OK.
  4. Se si verificano errori nell'operazione di scrittura, il messaggio Pub/Sub stesso viene confermato negativamente. Il messaggio viene poi inviato di nuovo. Se il messaggio non riesce un numero di volte sufficiente 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 un abbonamento a BigQuery determinano la tabella BigQuery in cui Pub/Sub scrive i messaggi e il tipo di schema di quella tabella.

Per ulteriori informazioni, consulta le proprietà BigQuery.

Compatibilità dello schema

Questa sezione è applicabile solo se selezioni l'opzione Utilizza schema argomento quando crei una sottoscrizione BigQuery.

Pub/Sub e BigQuery utilizzano metodi diversi per definire i propri schemi. Gli schemi Pub/Sub sono definiti in formato Apache Avro o Protocol Buffer, mentre gli schemi BigQuery sono definiti utilizzando una varietà di formati.

Di seguito è riportato un elenco di informazioni importanti sulla compatibilità dello schema tra un argomento Pub/Sub e una tabella BigQuery.

  • Qualsiasi messaggio contenente un campo con formato non corretto non viene scritto in BigQuery.

  • Nello schema BigQuery, INT, SMALLINT, INTEGER, BIGINT, TINYINT e BYTEINT sono alias per INTEGER; DECIMAL è un alias per NUMERIC e BIGDECIMAL è un alias per BIGNUMERIC.

  • Quando 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 dato BigQuery.

  • Sono supportati alcuni tipi logici Avro, come specificato nella tabella seguente. Eventuali tipi logici non elencati corrispondono solo al tipo Avro equivalente che annotano, come descritto nella specifica Avro.

Di seguito è riportata una raccolta di mappature di diversi formati di schema ai tipi di dati di BigQuery.

Tipi Avro

Tipo 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 corrispondente a null e l'altro a 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 del 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 di data e ora in formato intero

Quando esegui 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 all'intero che li rappresenta.

Tipo di dati BigQuery Rappresentazione di numeri interi
DATE Il numero di giorni dall'epoca Unix, 1° gennaio 1970
DATETIME La data e l'ora in microsecondi espresse come ora civile utilizzando CivilTimeEncoder
TIME L'ora in microsecondi espressa come ora civile utilizzando CivilTimeEncoder
TIMESTAMP Il numero di microsecondi dall'epoca di Unix, 00:00:00 UTC del 1° gennaio 1970

BigQuery Change Data Capture

Gli abbonamenti BigQuery supportano gli aggiornamenti di Change Data Capture (CDC) 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 i seguenti campi:

  • _CHANGE_TYPE (obbligatorio): un campo string impostato su UPSERT o DELETE.

    • Se un messaggio Pub/Sub scritto nella tabella BigQuery ha _CHANGE_TYPE impostato su UPSERT, BigQuery aggiorna la riga con la stessa chiave se esistente o inserisce una nuova riga se non esiste.

    • Se un messaggio Pub/Sub scritto nella tabella BigQuery ha _CHANGE_TYPE impostato su DELETE, BigQuery elimina la riga nella tabella con la stessa chiave, se esistente.

  • _CHANGE_SEQUENCE_NUMBER (facoltativo): un campo int64 (long) impostato per garantire che gli aggiornamenti e le eliminazioni apportati alla tabella BigQuery vengano elaborati in ordine. I messaggi per la stessa chiave di riga devono contenere un valore monotonicamente crescente per _CHANGE_SEQUENCE_NUMBER. I messaggi con numeri di sequenza inferiori al numero di sequenza più alto elaborato per una riga non hanno alcun effetto sulla riga nella tabella BigQuery. Tieni presente che Pub/Sub richiede un valore basato su numeri interi, diversamente dal valore basato su stringhe utilizzato quando interagisci direttamente con BigQuery.

Per utilizzare la funzionalità con use_table_schema, includi i campi precedenti 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 leggere i metadati della tabella. Per ulteriori informazioni, consulta Assegnare i ruoli BigQuery all'account del servizio Pub/Sub.

Gestire gli errori relativi ai messaggi

Quando non è possibile scrivere un messaggio Pub/Sub in BigQuery, il messaggio non può essere confermato. Per inoltrare questi messaggi non recapitabili, configura un argomento messaggi non recapitabili nell'abbonamento BigQuery. Il messaggio Pub/Sub forwardato all'argomento messaggi non recapitabili contiene un attributoCloudPubSubDeadLetterSourceDeliveryErrorMessage che indica il motivo per cui non è stato possibile scrivere il messaggio Pub/Sub in BigQuery.

Se Pub/Sub non riesce a scrivere i messaggi in BigQuery, ritira la consegna dei messaggi in modo simile al comportamento di backoff push. Tuttavia, se alla sostiscrizione è associato un argomento messaggi non recapitabili, Pub/Sub non esegue il ritiro della consegna quando gli errori dei messaggi sono dovuti a errori di compatibilità dello schema.

Quote e limiti

Esistono limitazioni di quota per il throughput degli abbonati BigQuery per regione. Per ulteriori informazioni, consulta Quote e limiti di Pub/Sub.

Le iscrizioni BigQuery scrivono i dati utilizzando l' API BigQuery Storage Write. Per informazioni su quote e limiti per l'API Storage Write, consulta le richieste dell'API BigQuery Storage Write. Gli abbonamenti BigQuery consumano solo la quota di throughput per l'API Storage Write. In questo caso, puoi ignorare le altre considerazioni relative alle quote dell'API Storage Write.

Prezzi

Per i prezzi delle sottoscrizioni BigQuery, consulta la pagina dei prezzi di Pub/Sub.

Passaggi successivi