Esportare i dati in Spanner (ETL inverso)

Questo documento descrive come configurare un flusso di lavoro di estrazione, trasformazione e caricamento inversi (ETL inverso) da BigQuery a Spanner. Puoi farlo utilizzando l'istruzione EXPORT DATA per esportare i dati dalle origini dati BigQuery, incluse le tabelle Iceberg, in una tabella Spanner.

Questo flusso di lavoro ETL inverso combina le funzionalità di analisi in BigQuery con bassa latenza e velocità effettiva elevata in Spanner. Questo flusso di lavoro ti consente di pubblicare dati per gli utenti dell'applicazione senza esaurire le quote e i limiti di BigQuery.

Prima di iniziare

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per esportare i dati BigQuery in Spanner, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Limitazioni

  • Questa funzionalità non è supportata in Assured Workloads.

  • I seguenti tipi di dati BigQuery non hanno equivalenti in Spanner e non sono supportati:

Dialetto del database Spanner Tipi BigQuery non supportati
Tutti i dialetti
  • STRUCT
  • GEOGRAPHY
  • DATETIME
  • RANGE
  • TIME
GoogleSQL
  • BIGNUMERIC: Il tipo di NUMERIC supportato non è abbastanza ampio. Valuta la possibilità di aggiungere cast espliciti al tipo NUMERIC nella query.

  • La dimensione massima di una riga esportata non può superare 1 MiB.

  • Spanner applica l'integrità referenziale durante l'esportazione. Se la tabella di destinazione è figlio di un'altra tabella (INTERLEAVE IN PARENT) o se la tabella di destinazione ha vincoli di chiave esterna, le chiavi esterne e la chiave padre verranno convalidate durante l'esportazione. Se una riga esportata viene scritta in una tabella con INTERLEAVE IN PARENT e la riga padre non esiste, l'esportazione non riuscirà e verrà visualizzato il messaggio "Parent row is missing. Errore "Impossibile scrivere la riga". Se la riga esportata viene scritta in una tabella con vincoli di chiave esterna e fa riferimento a una chiave inesistente, l'esportazione non riuscirà e verrà visualizzato l'errore "Violazione del vincolo di chiave esterna". Quando esporti in più tabelle, ti consigliamo di sequenziare l'esportazione per garantire che l'integrità referenziale venga mantenuta durante l'esportazione. In genere, questo significa esportare le tabelle principali e le tabelle a cui fanno riferimento le chiavi esterne prima delle tabelle che fanno riferimento a queste.

    Se la tabella di destinazione dell'esportazione ha vincoli di chiave esterna o è figlio di un'altra tabella (INTERLEAVE IN PARENT), la tabella padre deve essere compilata prima dell'esportazione di una tabella figlio e deve contenere tutte le chiavi corrispondenti. Il tentativo di esportare una tabella secondaria mentre una tabella principale non dispone del set completo di chiavi pertinenti non andrà a buon fine.

  • Un job BigQuery, ad esempio un job di estrazione in Spanner, ha una durata massima di 6 ore. Per informazioni sull'ottimizzazione dei job di estrazione di grandi dimensioni, vedi Ottimizzazione dell'esportazione. In alternativa, valuta la possibilità di dividere l'input in singoli blocchi di dati, che possono essere esportati come singoli job di estrazione.

  • Le esportazioni in Spanner sono supportate solo per le versioni BigQuery Enterprise o Enterprise Plus. L'edizione BigQuery Standard e il calcolo on demand non sono supportati.

  • Non puoi utilizzare le query continue per esportare nelle tabelle Spanner con chiavi primarie generate automaticamente.

  • Non puoi utilizzare le query continue per l'esportazione nelle tabelle Spanner in un database di dialetti PostgreSQL.

  • Quando utilizzi query continue per l'esportazione in una tabella Spanner, assicurati di scegliere una chiave primaria che non corrisponda a un numero intero in aumento monotono nella tabella BigQuery. In questo modo, potrebbero verificarsi problemi di rendimento nell'esportazione. Per informazioni sulle chiavi primarie in Spanner e sui modi per attenuare questi problemi di prestazioni, consulta Scegliere una chiave primaria.

Configurare le esportazioni con l'opzione spanner_options

Puoi utilizzare l'opzione spanner_options per specificare un database e una tabella Spanner di destinazione. La configurazione è espressa sotto forma di stringa JSON, come mostrato nell'esempio seguente:

EXPORT DATA OPTIONS(
   uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
   spanner_options = """{
      "table": "TABLE_NAME",
      "change_timestamp_column": "CHANGE_TIMESTAMP",
      "priority": "PRIORITY",
      "tag": "TAG",
   }"""
)

Sostituisci quanto segue:

  • PROJECT_ID: il nome del tuo Google Cloud progetto.
  • INSTANCE_ID: il nome dell'istanza del database.
  • DATABASE_ID: il nome del database.
  • TABLE_NAME: il nome di una tabella di destinazione esistente.
  • CHANGE_TIMESTAMP: il nome della colonna di tipo TIMESTAMP nella tabella Spanner di destinazione. Questa opzione viene utilizzata durante l'esportazione per monitorare il timestamp dell'aggiornamento più recente della riga. Quando questa opzione viene specificata, l'esportazione esegue prima una lettura della riga nella tabella Spanner per assicurarsi che venga scritta solo l'ultima riga aggiornata. Ti consigliamo di specificare una colonna di tipo TIMESTAMP quando esegui un'esportazione continua, in cui l'ordine delle modifiche alle righe con la stessa chiave primaria è importante.
  • (Facoltativo) PRIORITY: priorità delle richieste di scrittura. Valori consentiti: LOW, MEDIUM, HIGH. Valore predefinito: MEDIUM.
  • (Facoltativo) TAG: Tag richiesta per identificare il traffico dell'esportatore nel monitoraggio di Spanner. Valore predefinito: bq_export.

Requisiti per l'esportazione delle query

Per esportare i risultati della query in Spanner, questi devono soddisfare i seguenti requisiti:

  • Tutte le colonne nel set di risultati devono esistere nella tabella di destinazione e i relativi tipi devono corrispondere o essere convertibili.
  • Il set di risultati deve contenere tutte le colonne NOT NULL per la tabella di destinazione.
  • I valori delle colonne non devono superare i limiti di dimensione dei dati all'interno delle tabelle di Spanner.
  • Prima dell'esportazione in Spanner, tutti i tipi di colonne non supportati devono essere convertiti in uno dei tipi supportati.

Conversioni dei tipi

Per facilità d'uso, lo strumento di esportazione Spanner applica automaticamente le seguenti conversioni di tipo:

Tipo BigQuery Tipo di chiave
BIGNUMERIC NUMERIC (solo dialetto PostgreSQL)
FLOAT64 FLOAT32
BYTES PROTO
INT64 ENUM

Esporta i dati

Puoi utilizzare l'istruzione EXPORT DATA per esportare i dati da una tabella BigQuery in una tabella Spanner.

Il seguente esempio esporta i campi selezionati da una tabella denominata mydataset.table1:

EXPORT DATA OPTIONS (
  uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
  spanner_options="""{ "table": "TABLE_NAME" }"""
)
AS SELECT * FROM mydataset.table1;

Sostituisci quanto segue:

  • PROJECT_ID: il nome del tuo progetto Google Cloud
  • INSTANCE_ID: il nome dell'istanza del database
  • DATABASE_ID: il nome del database
  • TABLE_NAME: il nome di una tabella di destinazione esistente

Esportare più risultati con lo stesso valore di rowkey

Quando esporti un risultato contenente più righe con lo stesso valore rowkey, i valori scritti in Spanner finiscono nella stessa riga di Spanner. Nel set di righe Spanner prodotto dall'esportazione sarà presente solo una riga BigQuery corrispondente (non è garantito quale).

Esportare in modo continuo

Per elaborare continuamente una query di esportazione, consulta Creare query continue per istruzioni ed esempio di codice.

Ottimizzazione dell'esportazione

Per ottimizzare l'esportazione dei record da BigQuery a Spanner, puoi provare a:

  • Aumenta il numero di nodi nell'istanza di destinazione Spanner. Durante le prime fasi dell'esportazione, l'aumento del numero di nodi nell'istanza potrebbe non aumentare immediatamente la velocità effettiva di esportazione. Durante l'esecuzione della divisione basata sul carico, può verificarsi un leggero ritardo. Con la suddivisione basata sul carico, il throughput di esportazione aumenta e si stabilizza. L'utilizzo dell'istruzione EXPORT DATA raggruppa i dati per ottimizzare le scritture in Spanner. Per ulteriori informazioni, vedi Panoramica del rendimento.

  • Specifica la priorità HIGH all'interno di spanner_options. Se la tua istanza Spanner ha la scalabilità automatica abilitata, l'impostazione della priorità HIGH contribuisce a garantire che l'utilizzo della CPU raggiunga la soglia necessaria per attivare lo scaling. In questo modo, lo strumento di scalabilità automatica può aggiungere risorse di calcolo in risposta al carico di esportazione, il che può migliorare la velocità effettiva complessiva dell'esportazione.

    L'esempio seguente mostra un comando di esportazione Spanner impostato sulla priorità HIGH:

    EXPORT DATA OPTIONS (
  uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
  spanner_options="""{ "table": "TABLE_NAME", "priority": "HIGH" }"""
)

  • Evita di ordinare i risultati della query. Se il set di risultati contiene tutte le colonne della chiave primaria, l'esportatore ordina automaticamente le chiavi primarie della tabella di destinazione per semplificare le scritture e ridurre al minimo la contesa.

    Se la chiave primaria della tabella di destinazione include colonne generate, aggiungi le espressioni delle colonne generate alla query per assicurarti che i dati esportati vengano ordinati e raggruppati correttamente.

    Ad esempio, nel seguente schema Spanner, SaleYear e SaleMonth sono colonne generate che costituiscono l'inizio della chiave primaria Spanner:

    CREATE TABLE Sales (
  SaleId STRING(36) NOT NULL,
  ProductId INT64 NOT NULL,
  SaleTimestamp TIMESTAMP NOT NULL,
  Amount FLOAT64,
  -- Generated columns
  SaleYear INT64 AS (EXTRACT(YEAR FROM SaleTimestamp)) STORED,
  SaleMonth INT64 AS (EXTRACT(MONTH FROM SaleTimestamp)) STORED,
) PRIMARY KEY (SaleYear, SaleMonth, SaleId);

    Quando esporti dati da BigQuery a una tabella Spanner con colonne generate utilizzate nella chiave primaria, è consigliabile, ma non obbligatorio, includere le espressioni per queste colonne generate nella query EXPORT DATA. In questo modo BigQuery preordina correttamente i dati, il che è fondamentale per il batching e la scrittura efficienti in Spanner. I valori per le colonne generate nell'istruzione EXPORT DATA non vengono commitati in Spanner, perché vengono generati automaticamente da Spanner, ma vengono utilizzati per ottimizzare l'esportazione.

    L'esempio seguente esporta i dati in una tabella Spanner Sales la cui chiave primaria utilizza colonne generate. Per ottimizzare le prestazioni di scrittura, la query include espressioni EXTRACT che corrispondono alle colonne SaleYear e SaleMonth generate, consentendo a BigQuery di preordinare i dati prima dell'esportazione:

    EXPORT DATA OPTIONS (
  uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
  spanner_options="""{ "table": "Sales" }"""
)
AS SELECT
  s.SaleId,
  s.ProductId,
  s.SaleTimestamp,
  s.Amount,
  -- Add expressions that match the generated columns in the Spanner PK
  EXTRACT(YEAR FROM s.SaleTimestamp) AS SaleYear,
  EXTRACT(MONTH FROM s.SaleTimestamp) AS SaleMonth
FROM my_dataset.sales_export AS s;

  • Per evitare job di lunga durata, esporta i dati per partizione. Suddividi i dati BigQuery utilizzando una chiave di partizione, ad esempio un timestamp nella query:

    EXPORT DATA OPTIONS (
  uri="https://spanner.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID",
  format='CLOUD_SPANNER',
  spanner_options="""{ "table": "TABLE_NAME", "priority": "MEDIUM" }"""
)
AS SELECT *
FROM 'mydataset.table1' d
WHERE
d.timestamp >= TIMESTAMP '2025-08-28T00:00:00Z' AND
d.timestamp < TIMESTAMP '2025-08-29T00:00:00Z';

    In questo modo, la query viene completata entro il runtime del job di 6 ore. Per saperne di più su questi limiti, consulta i limiti dei job di query.

  • Per migliorare le prestazioni di caricamento dei dati, elimina l'indice nella tabella Spanner in cui vengono importati i dati. Poi ricrealo al termine dell'importazione.

  • Ti consigliamo di iniziare con un nodo Spanner (1000 unità di elaborazione) e una prenotazione minima di slot BigQuery. Ad esempio, 100 slot o 0 slot di riferimento con scalabilità automatica. Per le esportazioni inferiori a 100 GB, questa configurazione viene in genere completata entro il limite di 6 ore del job. Per le esportazioni superiori a 100 GB, aumenta la velocità effettiva scalando i nodi Spanner e le prenotazioni di slot BigQuery, in base alle esigenze. Il throughput viene scalato a circa 5 MiB/s per nodo.

Prezzi

Quando esporti i dati in Spanner utilizzando l'istruzione EXPORT DATA, la fatturazione viene eseguita utilizzando i prezzi di calcolo della capacità di BigQuery.

Per esportare continuamente in Spanner utilizzando una query continua, devi disporre di una prenotazione di slot BigQuery Enterprise o Enterprise Plus e di un assegnazione di prenotazione che utilizza il tipo di job CONTINUOUS.

Le esportazioni BigQuery in Spanner che attraversano i confini regionali vengono addebitate utilizzando le tariffe di estrazione dei dati. Per ulteriori informazioni, vedi Prezzi di BigQuery. Per evitare addebiti per il trasferimento di dati, assicurati che l'esportazione BigQuery venga eseguita nella stessa regione del leader predefinito di Spanner. Le esportazioni continue di query non supportano le esportazioni che attraversano i confini regionali.

Una volta esportati i dati, ti viene addebitato il costo di archiviazione dei dati in Spanner. Per ulteriori informazioni, consulta la pagina Prezzi di Spanner.