sottoscrizioni BigQuery

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

Una sottoscrizione BigQuery è un tipo di sottoscrizione di esportazione che scrive i messaggi in una tabella BigQuery esistente quando li ricevi. Non è necessario configurare un client abbonato 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. L'overhead associato all'esecuzione di un job Dataflow non è necessario quando i messaggi non richiedono ulteriori elaborazioni prima dell'archiviazione in una tabella BigQuery. Puoi utilizzare una sottoscrizione BigQuery.

Tuttavia, è comunque consigliata una pipeline Dataflow per i sistemi Pub/Sub in cui è necessaria una trasformazione dei dati prima che questi vengano archiviati in una tabella BigQuery. Per scoprire come trasmettere flussi di dati da Pub/Sub a BigQuery con la trasformazione utilizzando Dataflow, consulta Creare flussi di dati da Pub/Sub a BigQuery.

La sottoscrizione Pub/Sub al modello BigQuery da Dataflow applica "exactly-once la consegna per impostazione predefinita". Ciò avviene mediante meccanismi di deduplicazione all'interno della pipeline Dataflow. Tuttavia, l'abbonamento BigQuery supporta almeno una consegna. Se per il tuo caso d'uso è fondamentale la deduplicazione esatta, 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 sottoscrizioni supportati da Pub/Sub e perché 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 Write per inviare dati alla tabella BigQuery.
  2. I messaggi vengono inviati in batch alla tabella BigQuery.
  3. Dopo il completamento corretto di un'operazione di scrittura, l'API restituisce una risposta OK.
  4. In caso di errori nell'operazione di scrittura, il messaggio Pub/Sub stesso viene confermato negativamente. Il messaggio viene quindi inviato di nuovo. Se il messaggio restituisce un errore per un certo numero di volte 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 della tabella.

Per ulteriori informazioni, consulta Proprietà BigQuery.

Compatibilità degli schemi

Pub/Sub e BigQuery usano modi diversi per definire i propri schemi. Gli schemi Pub/Sub sono definiti nel formato Apache Avro o Protocol Buffer, mentre gli schemi BigQuery vengono definiti utilizzando vari formati. Di seguito è riportato un elenco di informazioni importanti relative alla compatibilità dello schema tra un argomento Pub/Sub e una tabella BigQuery.

  • I messaggi che contengono un campo formattato in modo non corretto non vengono scritti in BigQuery.

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

  • Quando il tipo nello schema dell'argomento è string e il tipo nella tabella BigQuery è JSON, TIMESTAMP, DATETIME, DATE, TIME, NUMERIC o BIGNUMERIC, tutti i valori di questo campo in un messaggio Pub/Sub devono 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 annotato, come descritto nella specifica Avro.

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

Tipi di 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 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

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 di un numero intero di data e ora

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 al numero intero che li rappresenta.

Tipo di dati BigQuery Rappresentazione con 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 il CivilTimeEncoder
TIME Il tempo in microsecondi espresso come ora civile utilizzando il CivilTimeEncoder.
TIMESTAMP Il numero di microsecondi dall'epoca di Unix, 1° gennaio 1970 00:00:00 UTC

Change Data Capture (BigQuery)

Le sottoscrizioni BigQuery supportano gli aggiornamenti Change Data Capture (CDC) quando use_topic_schema o use_table_schema sono impostati su true nelle proprietà della sottoscrizione. Per utilizzare la funzionalità con use_topic_schema, imposta lo schema dell'argomento con i campi seguenti:

  • _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 in caso contrario.

    • Se in un messaggio Pub/Sub scritto nella tabella BigQuery il valore _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) o int32 (int) impostato per garantire che gli aggiornamenti e le eliminazioni apportate alla tabella BigQuery vengano elaborati in ordine. I messaggi per la stessa chiave di riga devono contenere un valore che aumenta monotonicamente 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 della tabella BigQuery.

Per utilizzare la funzionalità con use_table_schema, includi i campi precedenti nel messaggio JSON.

Autorizzazioni per gli 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 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 questi 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 indica il motivo per cui non è stato possibile scrivere il messaggio Pub/Sub in BigQuery.

Quote e limiti

Sono previste limitazioni di quota per la velocità effettiva del sottoscrittore BigQuery per regione. Per ulteriori informazioni, consulta Quote e limiti di Pub/Sub.

Le sottoscrizioni BigQuery scrivono dati utilizzando l' API BigQuery Storage Write. Per informazioni su quote e limiti per l'API Storage Write, consulta Richieste API BigQuery Storage Write. Gli abbonamenti BigQuery utilizzano solo la quota di velocità effettiva per l'API Storage Write. Puoi ignorare le altre considerazioni relative alla quota dell'API Storage Write in questa istanza.

Prezzi

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

Passaggi successivi