Importa dati da database non Spanner

In questa pagina viene descritto come preparare i file Avro esportati da database non Cloud Spanner e poi importarli in Spanner. Se vuoi importare un database Spanner che hai esportato in precedenza, consulta Importare i file Avro Spanner.

Il processo utilizza Dataflow; importa i dati da un bucket Cloud Storage che contiene un set di file Avro e un file manifest JSON che specifica le tabelle di destinazione e i file Avro che completano ogni tabella.

Prima di iniziare

Per importare un database Spanner, devi prima abilitare le API Spanner, Cloud Storage, Compute Engine e Dataflow:

Abilita le API

Devi anche disporre di una quota sufficiente e delle autorizzazioni IAM richieste.

Requisiti per la quota

I requisiti di quota per i job di importazione sono i seguenti:

  • Scambia: devi disporre di una funzionalità di calcolo sufficiente per supportare la quantità di dati che stai importando. Non è richiesta alcuna capacità di calcolo aggiuntiva per importare un database, anche se potrebbe essere necessario aggiungere ulteriore capacità di calcolo in modo che il job venga completato in un tempo ragionevole. Per ulteriori dettagli, consulta Ottimizza i job.
  • Cloud Storage: per eseguire l'importazione, devi avere un bucket contenente i file esportati in precedenza. Non è necessario impostare una dimensione per il bucket.
  • Flusso di dati: i job di importazione sono soggetti alla stessa CPU, all'utilizzo del disco e allo stesso indirizzo IP delle quote di Compute Engine degli altri job Dataflow.
  • Compute Engine: prima di eseguire il job di importazione, devi configurare le quote iniziali per Compute Engine, che utilizza Dataflow. Queste quote rappresentano il numero massimo di risorse che consenti a Dataflow per utilizzare per il tuo job. I valori iniziali consigliati sono:

    • CPU: 200
    • Indirizzi IP in uso: 200
    • Disco permanente standard: 50 TB

    In genere, non devi apportare ulteriori modifiche. Dataflow fornisce la scalabilità automatica in modo che tu paghi solo per le risorse effettive utilizzate durante l'importazione. Se il tuo job può utilizzare più risorse, nell'interfaccia utente di Dataflow viene visualizzata un'icona di avviso. Il job deve terminare anche se è presente un'icona di avviso.

Requisiti IAM

Per importare un database, devi anche disporre di ruoli IAM con autorizzazioni sufficienti per utilizzare tutti i servizi coinvolti in un job di importazione. Per informazioni sulla concessione di ruoli e autorizzazioni, consulta Applicare ruoli IAM.

Per importare un database, devi disporre dei seguenti ruoli:

  • A livello di progetto Google Cloud:
    • Visualizzatore Spanner
    • Amministratore Dataflow
    • Amministratore Storage
  • A livello di database o istanza di Spanner oppure a livello di progetto Google Cloud:
    • Lettore Spanner
    • Amministratore database Spanner (obbligatorio solo per i job di importazione)

Esporta i dati da un database senza Spanner a file Avro

Il processo di importazione importa i dati dai file Avro situati in un bucket Cloud Storage. Puoi esportare i dati in formato Avro da qualsiasi origine e utilizzare qualsiasi metodo disponibile.

Per esportare i dati da un database senza Spanner a file Avro, procedi nel seguente modo:

Quando esporti i dati, tieni presente quanto segue:

  • Per eseguire l'esportazione, puoi utilizzare uno qualsiasi dei tipi di primitivi Avro e il tipo di complesso array.
  • Ogni colonna nei file Avro deve utilizzare uno dei seguenti tipi di colonna:

    • ARRAY
    • BOOL
    • BYTES*
    • DOUBLE
    • FLOAT
    • INT
    • LONG
    • STRING

    * Viene utilizzata una colonna di tipo BYTES per importare NUMERIC di Cloud Spanner. Consulta le mappature consigliate di seguito.

    †,‡ Puoi importare un timestamp che memorizza un timestamp o un STRING che memorizza un timestamp come Spanner TIMESTAMP; consulta le mappature consigliate di seguito per i dettagli.

  • Non è necessario includere o generare metadati quando esporti i file Avro.

  • Non è necessario seguire alcuna convenzione di denominazione specifica per i tuoi file.

Se non esporti i file direttamente in Cloud Storage, devi caricarli in un bucket Cloud Storage. Per istruzioni dettagliate, consulta la sezione Caricare oggetti su Cloud Storage.

Importa i file Avro da database non Spanner in Spanner

Per importare i file Avro da un database senza Spanner a Spanner, segui questi passaggi:

  1. Crea le tabelle di destinazione e definisci lo schema per il database Spanner.
  2. Crea un file spanner-export.json nel bucket Cloud Storage.
  3. Esegui un job di importazione Dataflow utilizzando l'interfaccia a riga di comando gcloud.

Passaggio 1: crea lo schema per il database Spanner

Prima di eseguire l'importazione, devi creare la tabella di destinazione in Spanner e definirne lo schema.

Devi creare uno schema che utilizzi il tipo di colonna appropriato per ogni colonna nei file Avro.

SQL standard di Google

Tipo di colonna Avro Tipo di colonna Spanner
ARRAY ARRAY
BOOL BOOL
BYTES

BYTES

NUMERIC (quando il tipo di colonna è BYTES e logicalType=decimal, precision=38 e scale=9). Se queste specifiche esatte vengono omesse, il campo viene considerato come un valore BYTES di Cloud Spanner. Per ulteriori informazioni, consulta la documentazione relativa al tipo logico decimale Avro.

DOUBLE FLOAT64
FLOAT FLOAT64
INT INT64
LONG

INT64

TIMESTAMP quando LONG rappresenta un timestamp del numero di microsecondi dal 1° gennaio 1970 00:00:00 UTC

STRING

STRING

TIMESTAMP quando STRING rappresenta un timestamp nel formato canonico per le query SQL

PostgreSQL

Tipo di colonna Avro Tipo di colonna Spanner
ARRAY ARRAY
BOOL BOOLEAN
BYTES

BYTEA

NUMERIC (quando il tipo di colonna è BYTEA e logicalType=decimal, precision=147455 e scale=16383). Se queste specifiche esatte vengono omesse, il campo viene considerato come un valore di BYTEA. Per ulteriori informazioni, consulta la documentazione relativa al tipo logico decimale Avro.

DOUBLE DOUBLE PRECISION
FLOAT DOUBLE PRECISION
INT BIGINT
LONG

BIGINT

TIMESTAMP quando LONG rappresenta un timestamp del numero di microsecondi dal 1° gennaio 1970 00:00:00 UTC

STRING

CHARACTER VARYING

TIMESTAMP quando STRING rappresenta un timestamp nel formato canonico per le query SQL, ad esempio '2022-05-28T07:08:21.123456789Z' o '2021-12-19T16:39:57-08:00'.

Passaggio 2: crea un file spanner-export.json

Devi anche creare un file denominato spanner-export.json nel tuo bucket Cloud Storage. Questo file specifica il dialetto del database e contiene un array tables che elenca il nome e le posizioni dei file di dati per ogni tabella.

I contenuti del file hanno il seguente formato:

{
  "tables": [
   {
    "name": "TABLE1",
    "dataFiles": [
      "RELATIVE/PATH/TO/TABLE1_FILE1",
      "RELATIVE/PATH/TO/TABLE1_FILE2"
    ]
   },
   {
    "name": "TABLE2",
    "dataFiles": ["RELATIVE/PATH/TO/TABLE2_FILE1"]
   }
  ],
  "dialect":"DATABASE_DIALECT"
}

Dove DATABASE_DIALECT = {GOOGLE_STANDARD_SQL | POSTGRESQL}

Se l'elemento dialetto viene omesso, il valore predefinito del dialetto è GOOGLE_STANDARD_SQL.

Passaggio 3: esegui un job di importazione Dataflow utilizzando l'interfaccia a riga di comando gcloud

Per avviare il job di importazione, segui le istruzioni per utilizzare l'interfaccia a riga di comando di Google Cloud per eseguire un job con il modello Avro a Spanner.

Dopo aver avviato un job di importazione, puoi visualizzarne i dettagli in Google Cloud Console.

Una volta completato il job di importazione, aggiungi gli indici secondari e le chiavi esterne necessari.

Scegli un'area geografica per il job di importazione

Ti consigliamo di scegliere un'area geografica diversa in base alla località del bucket Cloud Storage. Per evitare addebiti di rete in uscita, scegli un'area geografica che corrisponda alla località del bucket Cloud Storage.

  • Se la località del tuo bucket Cloud Storage è un'area geografica, puoi usufruire dell'utilizzo gratuito della rete scegliendo la stessa area geografica per il job di importazione, supponendo che tale area geografica sia disponibile.

  • Se la località del bucket Cloud Storage è una doppia area geografica, puoi usufruire dell'utilizzo della rete senza costi aggiuntivi scegliendo una delle due aree geografiche che compongono la doppia area geografica per il job di importazione, supponendo che una delle aree geografiche sia disponibile.

  • Se un'area geografica in cui si trova la stessa località non è disponibile per il job di importazione o se la località del bucket di Cloud Storage è più aree geografiche, vengono applicati i costi per il traffico in uscita. Fai riferimento ai prezzi del traffico di rete in uscita di Cloud Storage per scegliere un'area geografica che prevede i costi di traffico di rete più bassi.

Visualizzare o risolvere i problemi nei job nell'interfaccia utente di Dataflow

Dopo aver avviato un job di importazione, puoi visualizzarne i dettagli, inclusi i log, nella sezione Dataflow di Google Cloud Console.

Visualizza dettagli job Dataflow

Per visualizzare i dettagli di tutti i job di importazione/esportazione eseguiti nell'ultima settimana, inclusi gli eventuali job in esecuzione:

  1. Vai alla pagina Panoramica del database.
  2. Fai clic sulla voce di menu del riquadro a sinistra Importa/Esporta. La pagina Importa/Esporta del database mostra un elenco di job recenti.
  3. Nella pagina Importa/Esporta del database, fai clic sul nome del job nella colonna Nome job Dataflow:

    Messaggio di stato del job in corso

    Google Cloud Console visualizza i dettagli del job Dataflow.

Per visualizzare un lavoro che hai svolto più di una settimana fa:

  1. Vai alla pagina Job Dataflow in Google Cloud Console.

    Vai alla pagina delle offerte di lavoro

  2. Trova il lavoro nell'elenco, quindi fai clic sul nome.

    Google Cloud Console visualizza i dettagli del job Dataflow.

Visualizza i log di Dataflow per il job

Per visualizzare i log di un job Dataflow, vai alla pagina dei dettagli del job come descritto sopra, quindi fai clic su Logs a destra del nome del job.

Se un job non va a buon fine, cerca gli errori nei log. Se sono presenti errori, il numero di errori viene visualizzato accanto a Log:

Esempio di conteggio errori accanto al pulsante Log

Per visualizzare gli errori nel job:

  1. Fai clic sul numero di errori accanto a Log.

    Google Cloud Console visualizza i log del job. Potrebbe essere necessario scorrere per visualizzare gli errori.

  2. Individua le voci con l'icona di errore Icona di errore.

  3. Fai clic su una singola voce di log per espanderne i contenuti.

Per ulteriori informazioni sulla risoluzione dei problemi dei job Dataflow, consulta Risoluzione dei problemi della pipeline.

Risolvere i problemi relativi ai job di importazione non riusciti

Nei log dei job vengono visualizzati i seguenti errori:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Controlla la 99% di latenza di scrittura nella scheda Monitoring del database Cloud Spanner in Google Cloud Console. Se mostra valori elevati (più secondi), significa che l'istanza è sovraccarica, causando il timeout delle scritture e la mancata riuscita.

Una delle cause più elevate è l'esecuzione del job Dataflow utilizzando troppi worker, creando un carico eccessivo nell'istanza Cloud Spanner.

Per specificare un limite sul numero di worker di Dataflow, anziché utilizzare la scheda Importa/Esporta nella pagina dei dettagli dell'istanza del database Cloud Spanner in Google Cloud Console, devi avviare l'importazione utilizzando il modello Dataflow Da Avro a Cloud Spanner di Dataflow e specificare il numero massimo di worker come descritto di seguito:
  • Se utilizzi la console di Dataflow, il parametro Max worker si trova nella sezione Parametri facoltativi della pagina Crea job da modello.

  • Se utilizzi gcloud, specifica l'argomento max-workers. Ad esempio:

    gcloud dataflow jobs run my-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
    --max-workers=10
    

Ottimizza i job di importazione a esecuzione lenta

Se hai seguito i suggerimenti nelle impostazioni iniziali, in genere non dovresti effettuare altre modifiche. Se il tuo job viene eseguito lentamente, puoi provare alcune altre ottimizzazioni:

  • Ottimizza il job e la località dei dati: esegui il tuo job Dataflow nella stessa area geografica in cui si trovano l'istanza Spanner e il bucket Cloud Storage.

  • Assicurati che le risorse di Dataflow siano sufficienti: se le quote pertinenti di Compute Engine limitano le risorse del job Dataflow, nella pagina Dataflow del job vengono visualizzate un'icona di avviso Icona di avviso e i messaggi di log:

    Screenshot dell'avviso relativo al limite di quota

    In questa situazione, l'aumento delle quote per CPU, indirizzi IP in uso e disco permanente standard potrebbe ridurre il tempo di esecuzione del job, ma potrebbero essere addebitati più costi per Compute Engine.

  • Controlla l'utilizzo della CPU di Spanner. Se noti che l'utilizzo della CPU per l'istanza supera il 65%, puoi aumentare la funzionalità di calcolo in tale istanza. La capacità aggiunge più risorse Spanner e il job dovrebbe accelerare, ma ti verranno addebitati più addebiti.

Fattori che influiscono sulle prestazioni del job di importazione

Il tempo necessario per completare un job di importazione è influenzato da diversi fattori.

  • Dimensione del database Spanner: l'elaborazione di più dati richiede più tempo e risorse.

  • Schema del database Spanner, tra cui:

    • Il numero di tabelle
    • Le dimensioni delle righe
    • Il numero di indici secondari
    • Il numero di chiavi esterne
    • Il numero di flussi di modifiche

  • Posizione dei dati: i dati vengono trasferiti tra Spanner e Cloud Storage utilizzando Dataflow. Idealmente, tutti e tre i componenti si trovano nella stessa area geografica. Se i componenti non si trovano nella stessa area geografica, lo spostamento dei dati tra aree geografiche rallenta il job.

  • Numero di worker di Dataflow: i worker di Dataflow ottimali sono necessari per buone prestazioni. Utilizzando la scalabilità automatica, Dataflow sceglie il numero di worker per il job in base alla quantità di lavoro da eseguire. Tuttavia, il numero di worker sarà limitato dalle quote per CPU, indirizzi IP in uso e disco permanente standard. Se si verificano limiti di quota, l'interfaccia utente di Dataflow visualizza un'icona di avviso. In questa situazione, l'avanzamento è più lento, ma il job deve comunque essere completato. La scalabilità automatica può sovraccaricare Spanner, causando errori, in caso di una grande quantità di dati da importare.

  • Carico esistente su Spanner: un job di importazione aggiunge un carico CPU significativo su un'istanza Spanner. Se l'istanza ha già un carico esistente, il job viene eseguito più lentamente.

  • Quantità di capacità di calcolo di Spanner: se l'utilizzo della CPU per l'istanza è superiore al 65%, il job viene eseguito più lentamente.

Regola i worker per ottenere prestazioni di importazione elevate

Durante l'avvio di un job di importazione di Spanner, i worker di Dataflow devono essere impostati su un valore ottimale per le buone prestazioni. Troppi worker sovraccaricano Spanner e il numero di worker è troppo basso e le prestazioni dell'importazione potrebbero essere inferiori.

Il numero massimo di worker dipende fortemente dalle dimensioni dei dati, ma idealmente, l'utilizzo totale della CPU Spanner deve essere compreso tra 70% e 90%. Offre un buon equilibrio tra l'efficienza di Spanner e il completamento del job senza errori.

Per raggiungere il target di utilizzo nella maggior parte degli schemi/scenari, consigliamo un numero massimo di vCPU worker compreso tra 4 e 6 volte il numero di nodi Spanner.

Ad esempio, per un'istanza di 10 nodi, utilizzando worker n1-standard-2, il numero di worker dovrebbe essere impostato su 25, per un totale di 50 vCPU.