Questa pagina descrive come preparare i file Avro esportati da database non Spanner e quindi importarli in Spanner. Se vuoi importare un database Spanner che hai esportato in precedenza, consulta Importare file Avro Spanner.
Il processo utilizza Dataflow, importa i dati da un bucket Cloud Storage contenente un set di file Avro e un file manifest JSON che specifica le tabelle di destinazione e i file Avro che popolano ogni tabella.
Prima di iniziare
Per importare un database Spanner, devi prima abilitare le API Spanner, Cloud Storage, Compute Engine e Dataflow:
Devi anche avere una quota sufficiente e le autorizzazioni IAM richieste.
Requisiti per le quote
I requisiti di quota per i job di importazione sono i seguenti:
- Spanner: devi avere una capacità di calcolo sufficiente per supportare la quantità di dati che importi. Non è richiesta alcuna capacità di calcolo aggiuntiva per importare un database, ma potresti dover aggiungere ulteriore capacità di calcolo in modo che il job venga completato in un periodo di tempo ragionevole. Per ulteriori dettagli, consulta Ottimizzare le offerte di lavoro.
- Cloud Storage: per eseguire l'importazione, devi avere un bucket contenente i file esportati in precedenza. Non è necessario impostare una dimensione per il bucket.
- Dataflow: i job di importazione sono soggetti alle stesse quote di Compute Engine di CPU, disco e indirizzo IP degli altri job Dataflow.
Compute Engine: prima di eseguire il job di importazione, devi configurare le quote iniziali per Compute Engine, utilizzato da Dataflow. Queste quote rappresentano il numero massimo di risorse che puoi consentire a Dataflow di 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 è necessario apportare altre modifiche. La scalabilità automatica di Dataflow ti consente di pagare solo per le risorse effettivamente utilizzate durante l'importazione. Se il job può utilizzare più risorse, l'interfaccia utente di Dataflow mostra un'icona di avviso. Il job dovrebbe terminare anche se è presente un'icona di avviso.
Requisiti IAM
Per importare un database, devi inoltre 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:
- Spanner Viewer (
roles/spanner.viewer) - Amministratore Dataflow (
roles/dataflow.admin) - Storage Admin (
roles/storage.admin)
- Spanner Viewer (
- A livello di istanza o database Spanner o a livello di progetto Google Cloud:
- Lettore database Spanner (
roles/spanner.databaseReader) - Amministratore database Spanner (
roles/spanner.databaseAdmin)
- Lettore database Spanner (
Esporta i dati da un database non Spanner in file Avro
Il processo di importazione importa i dati da file Avro che si trovano in un bucket Cloud Storage. Puoi esportare i dati in formato Avro da qualsiasi origine e utilizzare qualsiasi metodo disponibile per farlo.
Per esportare i dati da un database non Spanner in file Avro, segui questi passaggi:
Quando esporti i dati, tieni presente quanto segue:
- Puoi esportare i dati utilizzando qualsiasi tipo primitivo Avro e il tipo complesso array.
Ogni colonna dei file Avro deve utilizzare uno dei seguenti tipi di colonna:
ARRAYBOOLBYTES*DOUBLEFLOATINTLONG†STRING‡
* Una colonna di tipo
BYTESviene utilizzata per importare unNUMERICdi Spanner. Per maggiori dettagli, consulta le mappature consigliate di seguito.†,‡ Puoi importare un
LONGche contiene un timestamp o unSTRINGche memorizza un timestamp come SpannerTIMESTAMP; consulta le mappature consigliate di seguito per i dettagli.Non è necessario includere o generare metadati quando esporti i file Avro.
Non è necessario seguire una particolare convenzione di denominazione per i file.
Se non esporti i file direttamente in Cloud Storage, devi caricare i file Avro in un bucket Cloud Storage. Per istruzioni dettagliate, vedi Caricamento di oggetti in Cloud Storage.
Importa file Avro da database non Spanner in Spanner
Per importare file Avro da un database non Spanner in Spanner, segui questi passaggi:
- Creare tabelle di destinazione e definire lo schema per il database Spanner.
- Crea un file
spanner-export.jsonnel bucket Cloud Storage. - Esegui un job di importazione di Dataflow utilizzando gcloud CLI.
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.
Mappature consigliate
GoogleSQL
| Tipo di colonna Avro | Tipo di colonna Spanner |
|---|---|
ARRAY |
ARRAY |
BOOL |
BOOL |
BYTES |
|
DOUBLE |
FLOAT64 |
FLOAT |
FLOAT64 |
INT |
INT64 |
LONG |
|
STRING |
|
PostgreSQL
| Tipo di colonna Avro | Tipo di colonna Spanner |
|---|---|
ARRAY |
ARRAY |
BOOL |
BOOLEAN |
BYTES |
|
DOUBLE |
DOUBLE PRECISION |
FLOAT |
DOUBLE PRECISION |
INT |
BIGINT |
LONG |
|
STRING |
|
Passaggio 2: crea un file spanner-export.json
Devi inoltre 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 del dialetto viene omesso, il valore predefinito del dialetto è GOOGLE_STANDARD_SQL.
Passaggio 3: esegui un job di importazione di Dataflow utilizzando gcloud CLI
Per avviare il job di importazione, segui le istruzioni per l'utilizzo di Google Cloud CLI al fine di eseguire un job con il modello Da Avro a Spanner.
Dopo aver avviato un job di importazione, puoi visualizzare i relativi dettagli nella console Google Cloud.
Al termine del job di importazione, aggiungi eventuali indici secondari e chiavi esterne necessari.
Scegli una regione per il job di importazione
Potresti voler scegliere una regione diversa in base alla località del bucket Cloud Storage. Per evitare addebiti per il trasferimento di dati in uscita, scegli una regione che corrisponda alla località del bucket Cloud Storage.
Se la località del bucket Cloud Storage è una regione, puoi sfruttare l'utilizzo gratuito della rete scegliendo la stessa regione per il job di importazione, supponendo che quella regione sia disponibile.
Se la località del bucket Cloud Storage è due regioni, puoi sfruttare l'utilizzo gratuito della rete scegliendo una delle due regioni che compongono la doppia regione per il job di importazione, supponendo che una delle regioni sia disponibile.
Se una regione con sede condivisa non è disponibile per il job di importazione o se la località del bucket Cloud Storage è più regioni, si applicano i costi per il trasferimento di dati in uscita. Consulta i prezzi del trasferimento di dati di Cloud Storage per scegliere una regione che comporta i costi più bassi per il trasferimento di dati.
Visualizza o risolvi i problemi dei job nell'interfaccia utente di Dataflow
Dopo aver avviato un job di importazione, puoi visualizzare i dettagli del job, inclusi i log, nella sezione Dataflow della console Google Cloud.
Visualizza i dettagli del job Dataflow
Per visualizzare i dettagli di eventuali job di importazione/esportazione eseguiti nell'ultima settimana, inclusi eventuali job attualmente in esecuzione:
- Vai alla pagina Panoramica del database per il database.
- Fai clic sulla voce di menu Importa/Esporta nel riquadro a sinistra. La pagina Importa/Esporta del database mostra un elenco dei job recenti.
Nella pagina Importa/Esporta del database, fai clic sul nome del job nella colonna Nome job Dataflow:
La console Google Cloud mostra i dettagli del job Dataflow.
Per visualizzare un job eseguito più di una settimana fa:
Vai alla pagina dei job Dataflow nella console Google Cloud.
Trova il lavoro nell'elenco, quindi fai clic sul suo nome.
La console Google Cloud mostra i dettagli del job Dataflow.
Visualizza i log di Dataflow per il tuo job
Per visualizzare i log di un job Dataflow, vai alla pagina dei dettagli del job come descritto in precedenza, quindi fai clic su Log a destra del nome del job.
Se un job ha esito negativo, cerca gli errori nei log. In caso di errori, il numero di errori viene visualizzato accanto a Log:
Per visualizzare gli errori del job:
Fai clic sul conteggio degli errori accanto a Log.
La console Google Cloud visualizza i log del job. Potrebbe essere necessario scorrere per vedere gli errori.
Individua le voci con l'icona di errore
.Fai clic su una singola voce di log per espanderne il contenuto.
Per ulteriori informazioni sulla risoluzione dei problemi dei job Dataflow, consulta Risolvere i problemi della pipeline.
Risolvere i problemi relativi ai job di importazione non riusciti
Se nei log del 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.
Verifica la latenza di scrittura del 99% nella scheda Monitoring del tuo database Spanner nella console Google Cloud. Se vengono mostrati valori elevati (più secondi), significa che l'istanza è sovraccarica, con conseguente timeout e esito negativo delle scritture.
Una delle cause della latenza elevata è che il job Dataflow è in esecuzione con troppi worker, causando un carico eccessivo sull'istanza Spanner.
Per specificare un limite per il numero di worker Dataflow, invece di utilizzare la scheda Importa/Esporta nella pagina dei dettagli dell'istanza del database Spanner nella console Google Cloud, devi avviare l'importazione utilizzando il modello di Dataflow da Cloud Storage Avro a Cloud Spanner e specificare il numero massimo di worker come descritto di seguito:Se utilizzi la console 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, di solito non dovresti apportare altre modifiche. Se il job viene eseguito lentamente, puoi provare alcune altre ottimizzazioni:
Ottimizza il job e la posizione dei dati: esegui il job Dataflow nella stessa regione in cui si trovano l'istanza Spanner e il bucket Cloud Storage.
Garantire risorse Dataflow sufficienti: se le quote di Compute Engine pertinenti limitano le risorse del job Dataflow, la pagina Dataflow del job nella console Google Cloud mostra un'icona di avviso
e messaggi di log:
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 esserti addebitati maggiori 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 capacità di calcolo nell'istanza. La capacità aggiunge più risorse di Spanner e il job dovrebbe essere più veloce, ma ti vengono addebitati più costi di Spanner.
Fattori che influiscono sulle prestazioni del job di importazione
Il tempo necessario per completare un job di importazione dipende da diversi fattori.
Dimensione del database di Spanner: l'elaborazione di più dati richiede più tempo e risorse.
Schema del database Spanner, tra cui:
- Il numero di tabelle
- La dimensione delle righe
- Il numero di indici secondari
- Il numero di chiavi esterne
- Il numero di modifiche in tempo reale
Posizione dei dati: i dati vengono trasferiti tra Spanner e Cloud Storage utilizzando Dataflow. Idealmente, tutti e tre i componenti si trovano nella stessa regione. Se i componenti non si trovano nella stessa regione, lo spostamento dei dati tra regioni rallenta il job.
Numero di worker Dataflow: sono necessari i worker Dataflow ottimali per ottenere buone prestazioni. Utilizzando la scalabilità automatica, Dataflow sceglie il numero di worker per il job in base alla quantità di lavoro da svolgere. Tuttavia, il numero di worker sarà limitato dalle quote per CPU, indirizzi IP in uso e disco permanente standard. L'interfaccia utente di Dataflow mostra un'icona di avviso se rileva limiti di quota. In questa situazione, l'avanzamento è più lento, ma il job dovrebbe comunque essere completato. La scalabilità automatica può sovraccaricare Spanner causando errori quando è presente una grande quantità di dati da importare.
Carico esistente su Spanner: un job di importazione aggiunge un carico significativo della CPU su un'istanza Spanner. Se l'istanza ha già un carico esistente sostanziale, 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.
Ottimizza i worker per ottenere buone prestazioni di importazione
Quando si avvia un job di importazione Spanner, i worker Dataflow devono essere impostati su un valore ottimale per buone prestazioni. Troppi worker sovraccarica Spanner e un numero troppo basso di worker si traduce in prestazioni di importazione inferiori.
Il numero massimo di worker dipende fortemente dalla dimensione dei dati, ma idealmente, l'utilizzo totale della CPU Spanner dovrebbe essere compreso tra il 70% e il 90%. Questo offre un buon equilibrio tra efficienza di Spanner e completamento di job senza errori.
Per raggiungere il target di utilizzo nella maggior parte degli schemi e degli scenari, consigliamo un numero massimo di vCPU worker compreso tra 4 e 6 volte il numero di nodi Spanner.
Ad esempio, per un'istanza Spanner a 10 nodi, utilizzando worker n1-standard-2, imposta il numero massimo di worker su 25, per 50 vCPU.