Importa dati da database non Spanner

Questa pagina descrive come preparare i file Avro da cui hai esportato non Spanner e importarli in Spanner. Se vuoi importare un database Spanner che hai esportato in precedenza, consulta Importa file Avro Spanner.

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

Prima di iniziare

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

Enable the APIs

Devi anche avere una quota sufficiente e le autorizzazioni IAM richieste.

Requisiti delle quote

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

• Spanner: devi avere una capacità di calcolo sufficiente in base alla quantità di dati che importi. Nessun altro necessaria per importare un database, anche se potresti aver bisogno per aggiungere più capacità di calcolo in modo che il job venga completato in una quantità ragionevole del tempo. Per ulteriori dettagli, consulta la sezione Job di ottimizzazione.
• Cloud Storage: per 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 per CPU, utilizzo del disco e indirizzo IP degli altri job Dataflow.

• Compute Engine: prima di eseguire il job di importazione, devi configurare quote iniziali di Compute Engine, usato da Dataflow. Queste quote rappresentano il numero massimo di risorse consentite Dataflow da 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. Dataflow fornisce la scalabilità automatica, in modo da pagare solo per le risorse effettive utilizzate durante l'importazione. Se il tuo lavoro può utilizzare altre risorse, la UI di Dataflow mostra un'icona di avviso. La il job dovrebbe terminare anche se è presente un'icona di avviso.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per esportare un database, chiedi all'amministratore di concederti seguenti ruoli IAM sull'account di servizio worker Dataflow:

• Visualizzatore Cloud Spanner (roles/spanner.viewer)
• Worker Dataflow (roles/dataflow.worker)
• Amministratore archiviazione (roles/storage.admin)
• Spanner Database Reader (roles/spanner.databaseReader)
• Amministratore database (roles/spanner.databaseAdmin)

Nota: il ruolo Amministratore database Spanner è richiesto solo per i job di importazione.

Esportare 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 nel bucket Cloud Storage. Puoi esportare i dati in formato Avro da qualsiasi origine e puoi utilizzare qualsiasi metodo disponibile per farlo.

Per esportare i dati da un database non Spanner in file Avro: questi passaggi:

Quando esporti i dati, tieni presente quanto segue:

• Puoi eseguire l'esportazione utilizzando uno dei tipi primitivi Avro, nonché il tipo complesso array.

• Ogni colonna dei file Avro deve utilizzare uno dei seguenti tipi di colonna:

  • ARRAY
  • BOOL
  • BYTES^*
  • DOUBLE
  • FLOAT
  • INT
  • LONG^†
  • STRING^‡

  ^* Una colonna di tipo BYTES viene utilizzata per importare un NUMERIC di Spanner. Per informazioni dettagliate, consulta la sezione Mappature consigliate di seguito.

  ^†,‡ Puoi importare un LONG che memorizza un timestamp o un STRING che memorizza un timestamp come TIMESTAMP Spanner; per maggiori dettagli, consulta la sezione seguente sulle mappature consigliate.

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

• Non è necessario seguire una particolare convenzione di denominazione per i file.

Se non esporti i file direttamente in Cloud Storage, devi: i file Avro in un bucket Cloud Storage. Per dettagli vedi Caricare oggetti in Cloud Storage.

Importa file Avro da database non Spanner in Spanner

Per importare i file Avro da un database non Spanner in Spanner:

1. Creare tabelle di destinazione e definire lo schema per il database Spanner.
2. Crea un file spanner-export.json nel bucket Cloud Storage.
3. 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	BYTES NUMERIC (se il tipo di colonna è BYTES e logicalType=decimal, precision=38 e scale=9. Se queste specifiche esatte vengono omesse, il campo viene considerato un valore BYTES di Spanner. Per ulteriori informazioni, consulta la documentazione del tipo logico decimale Avro.
DOUBLE	FLOAT64
FLOAT	FLOAT64
INT	INT64
LONG	INT64 TIMESTAMP quando LONG rappresenta un timestamp del numero di microsecondi a partire dal 1° gennaio 1970 alle ore 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 (se 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 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".

Nota: se una colonna dei dati Avro contiene valori NULL, devi assicurarti di impostare la colonna corrispondente nella tabella Spanner come nullable.

Passaggio 2: crea un file spanner-export.json

Devi anche creare un file denominato spanner-export.json nel tuo nel 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.

Nota: i caratteri jolly non sono supportati, devi scrivere per intero tutti i nomi file.

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 per eseguire un job con il modello Avro to Spanner.

Dopo aver avviato un job di importazione, puoi visualizzare i relativi dettagli in la console Google Cloud.

Al termine del job di importazione, aggiungi gli indici secondari e le chiavi esterne necessari.

Nota: per evitare addebiti per il trasferimento di dati in uscita, scegli una regione che si sovrappone alla località del bucket Cloud Storage. Per saperne di più, consulta la sezione Scegliere una regione di seguito.

Nota: il job Dataflow non risolve le tabelle interlacciate o i vincoli delle chiavi esterne, pertanto potresti riscontrare errori di scrittura a causa di violazioni dell'integrità referenziale. Rimuovi tutte le relazioni di interfoliazione o le chiavi esterne prima di avviare il job Dataflow.

Scegli una regione per il job di importazione

Ti consigliamo di scegliere una regione diversa in base alla località in cui si trova nel 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 posizione del bucket Cloud Storage è una regione, puoi usufruire dell'utilizzo gratuito della rete scegliendo la stessa regione per il job di importazione, a condizione che 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 per il job di importazione non è disponibile una regione in co-locazione o se la località del bucket Cloud Storage è una regione multipla, si applicano gli addebiti per il trasferimento di dati in uscita. Fai riferimento a Cloud Storage Data Transfer per scegliere una regione che prevede il 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 visualizzarne i dettagli, 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 o esportazione eseguiti nell'ultima settimana, inclusi quelli in esecuzione:

1. Vai alla pagina Panoramica del database per il database.
2. Fai clic sull'elemento di menu Importazione/esportazione nel riquadro di sinistra. Il database La pagina Importa/Esporta mostra un elenco dei job recenti.

3. Nella pagina Importa/Esporta del database, fai clic sul nome del job nella Colonna Nome job Dataflow:

   

   La console Google Cloud mostra i dettagli di Dataflow un lavoro.

Per visualizzare un job eseguito più di una settimana fa:

1. Vai alla pagina dei job Dataflow nella console Google Cloud.

   Vai a Job

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

   La console Google Cloud mostra i dettagli del job Dataflow.

di Gemini Advanced.

Nota: i job dello stesso tipo per lo stesso database hanno lo stesso nome. Puoi distinguere i job in base ai valori nelle colonne Start time (Ora di inizio) o End time (Ora di fine).

Visualizzare i log di Dataflow per il job

Per visualizzare i log di un job Dataflow, vai ai dettagli del job quindi fai clic su Log a destra del nome del job.

Se un job non va a buon fine, cerca gli errori nei log. Se ci sono errori, l'errore il conteggio delle voci viene visualizzato accanto a Log:

Per visualizzare gli errori del job:

1. Fai clic sul conteggio degli errori accanto a Log.

   La console Google Cloud mostra i log del job. Potresti dover scorrere per visualizzare gli errori.

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

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

Per ulteriori informazioni sulla risoluzione dei problemi dei job Dataflow, consulta Risolvi 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.

Controlla il Latenza di scrittura del 99% in Monitoring del tuo database Spanner nella nella console Google Cloud. Se vengono visualizzati valori elevati (più secondi), significa che l'istanza è sovraccaricata, causando il timeout e il fallimento delle scritture.

Una causa della latenza elevata è che il job Dataflow viene eseguito utilizzando troppi worker, il che comporta un carico eccessivo sull'istanza Spanner.

per specificare un limite al numero di worker Dataflow, anziché utilizzando la scheda Importa/Esporta nella pagina dei dettagli dell'istanza del nella console Google Cloud, devi avvia l'importazione utilizzando Dataflow Modello da Avro a Spanner di Cloud Storage e specificare il numero massimo di worker come descritto:

Console

Se utilizzi la console Dataflow, il campo Numero massimo di worker si trova nella sezione Parametri facoltativi della Pagina Crea job da modello.

Vai a Dataflow

gcloud

Esegui il comando gcloud dataflow jobs run e 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 \
    --network=network-123

Risolvere gli errori di rete

Quando esporti i database Spanner, potrebbe verificarsi il seguente errore:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

Questo errore si verifica perché Spanner presuppone che tu voglia utilizzare una rete VPC in modalità automatica denominata default nello stesso progetto del job Dataflow. Se non hai una rete VPC predefinita nel progetto o se la tua rete VPC è in modalità personalizzata, devi creare un job Dataflow e specificare una rete o una subnet alternativa.

Ottimizzare i job di importazione con esecuzione lenta

Se hai seguito i suggerimenti nelle impostazioni iniziali, in genere non devi apportare altre modifiche. Se il job funziona lentamente, puoi provare alcune altre ottimizzazioni:

• Ottimizza la posizione del job e dei dati: esegui il job Dataflow nella stessa regione in cui si trovano l'istanza Spanner e il bucket Cloud Storage.

• Assicurati di disporre di risorse Dataflow sufficienti: se le quote Compute Engine pertinenti limitano le risorse del tuo 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 le CPU, gli indirizzi IP in uso e i dischi permanenti standard potrebbe ridurre il tempo di esecuzione del job, ma potresti incorrere in più costi di Compute Engine.

• Verifica l'utilizzo della CPU di Spanner: se noti che l'utilizzo della CPU per l'istanza è superiore al 65%, puoi aumentare la capacità di calcolo in quell'istanza. La capacità aumenta Le risorse Spanner e il job dovrebbero essere più veloci, ma il traffico è maggiore Spanner addebita dei costi.

Fattori che influiscono sul rendimento del job di importazione

Diversi fattori influiscono sul tempo necessario per completare un job di importazione.

• 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

• Località dei dati: i dati vengono trasferiti tra Spanner e Cloud Storage usando Dataflow. Possibilmente, tutte e tre si trovano nella stessa regione. Se i componenti non si trovano nella stessa regione, lo spostamento dei dati tra le regioni rallenta il job.

• Numero di worker Dataflow: Dataflow ottimale sono necessari 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. Il numero di i worker saranno tuttavia limitati dalle quote di CPU, indirizzi IP in uso, e un disco permanente standard. L'interfaccia utente di Dataflow mostra un'icona di avviso se vengono raggiunti i limiti di quota. In questa situazione, l'avanzamento è più lento, ma il job dovrebbe comunque essere completato. La scalabilità automatica può sovraccaricare Spanner e causare errori quando è presente una grande quantità di dati da importare.

• Carico esistente su Spanner: un job di importazione aggiunge sulla CPU per un'istanza Spanner. Se l'istanza ha già un carico esistente sostanziale, il job esegue 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.

Ottimizzare i worker per un buon rendimento dell'importazione

Quando si avvia un job di importazione di Spanner, Dataflow i worker devono essere impostati su un valore ottimale per ottenere buone prestazioni. Troppi worker sovraccaricano Spanner e troppo pochi worker comportano prestazioni di importazione deludenti.

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

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

Ad esempio, per un'istanza Spanner di 10 nodi, utilizzando worker n1-standard-2, dovresti impostare il numero massimo di worker su 25, ottenendo 50 vCPU.