Importare ed esportare i dati in formato CSV

Questa pagina descrive come esportare i dati da Spanner a file CSV o importare i dati da file CSV in un database Spanner.

• Se vuoi importare un database Spanner che hai esportato in precedenza in file Avro in Cloud Storage, consulta Importare i file Avro Spanner.
• Se vuoi importare file Avro da un database non Spanner, consulta Importare dati da database non Spanner.

Il processo utilizza Dataflow. Puoi esportare i dati da Spanner a un bucket Cloud Storage oppure importarli in Spanner da un bucket Cloud Storage che contiene un file manifest JSON e un set di file CSV.

Nota: per esplorare Spanner utilizzando un'istanza di prova gratuita di 90 giorni, consulta Creare un'istanza di prova gratuita di Spanner.

Prima di iniziare

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

Abilita le API

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

Requisiti per le quote

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

• Spanner: devi avere una capacità di calcolo sufficiente per supportare la quantità di dati che stai importando. Non è necessaria alcuna capacità di calcolo aggiuntiva per importare o esportare un database, anche se potrebbe essere necessario aggiungerne maggiore in modo che il job venga completato in un periodo di tempo ragionevole. Per ulteriori dettagli, vedi Ottimizzare i lavori.
• Cloud Storage: per l'importazione, devi avere un bucket contenente i file esportati in precedenza. Per eseguire l'esportazione, devi creare un bucket per i file esportati, se non ne hai già uno. Puoi farlo nella console Google Cloud, tramite la pagina Cloud Storage o durante la creazione dell'esportazione tramite la pagina Spanner. Non è necessario impostare le dimensioni del bucket.
• Dataflow: i job di importazione o esportazione sono soggetti alle stesse quote di Compute Engine di CPU, utilizzo del disco e indirizzo IP degli altri job Dataflow.

• Compute Engine: prima di eseguire il job di importazione o esportazione, devi impostare le quote iniziali per Compute Engine, utilizzato da Dataflow. Queste quote rappresentano il numero massimo di risorse che Dataflow può 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 altre modifiche. Dataflow fornisce la scalabilità automatica in modo che tu paghi solo per le risorse effettive utilizzate durante l'importazione o l'esportazione. Se il job può utilizzare più risorse, la UI di Dataflow mostra un'icona di avviso. Il job dovrebbe terminare anche se è presente un'icona di avviso.

Requisiti IAM

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

Per importare o esportare un database, devi disporre dei seguenti ruoli:

• A livello di progetto Google Cloud:
  • Spanner Viewer (roles/spanner.viewer)
  • Amministratore Dataflow (roles/dataflow.admin)
  • Amministratore Storage (roles/storage.admin)
• A livello di database o istanza Spanner oppure a livello di progetto Google Cloud:
  • Lettore database Spanner (roles/spanner.databaseReader)
  • Amministratore database Spanner (roles/spanner.databaseAdmin)

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

Esportare i dati di Spanner in file CSV

Per esportare i dati da Spanner in file CSV in Cloud Storage, segui le istruzioni per utilizzare Google Cloud CLI per eseguire un job con il modello di testo da Spanner a Cloud Storage.

Puoi anche fare riferimento alle informazioni contenute in questo documento su visualizzazione o risoluzione dei problemi dei job, ottimizzazione dei job lenti e fattori che influiscono sulle prestazioni dei job.

Nota: non vengono esportati né i dati delle modifiche né i valori nelle colonne generate archiviate.

Importa dati da file CSV in Spanner

La procedura per importare dati dai file CSV prevede i seguenti passaggi:

1. Esporta i dati in file CSV e archiviali in Cloud Storage. Non includere una riga di intestazione.
2. Crea un file manifest JSON e archivialo insieme ai file CSV.
3. Crea tabelle di destinazione vuote nel database Spanner oppure assicurati che i tipi di dati per le colonne nei file CSV corrispondano a qualsiasi colonna corrispondente nelle tabelle esistenti.
4. Esegui il job di importazione.

Passaggio 1: esporta i dati da un database non Spanner in file CSV

Il processo di importazione importa i dati dai file CSV che si trovano in un bucket Cloud Storage. Puoi esportare i dati in formato CSV da qualsiasi origine.

Quando esporti i dati, tieni presente quanto segue:

• I file di testo da importare devono essere in formato CSV.

• I dati devono corrispondere a uno dei seguenti tipi:

GoogleSQL

BOOL
INT64
FLOAT64
NUMERIC
STRING
DATE
TIMESTAMP
BYTES
JSON

PostgreSQL

boolean
bigint
double precision
numeric
character varying, text
date
timestamp with time zone
bytea

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

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

Se non esporti i file direttamente in Cloud Storage, devi caricare i file CSV in un bucket Cloud Storage.

Passaggio 2: crea un file manifest JSON

Devi inoltre creare un file manifest con una descrizione JSON dei file da importare e posizionarlo nello stesso bucket Cloud Storage in cui hai archiviato i tuoi file CSV. Questo file manifest contiene un array tables che elenca i nomi e le posizioni dei file di dati per ogni tabella. Il file specifica anche il dialetto del database di destinazione. Se il dialetto viene omesso, per impostazione predefinita sarà GoogleSQL.

Nota: se una tabella ha colonne generate, il file manifest deve includere un elenco esplicito delle colonne non generate da importare per quella tabella. Spanner utilizza questo elenco per mappare le colonne CSV alle colonne della tabella corrette. I valori delle colonne generati vengono calcolati automaticamente durante l'importazione.

Il formato del file manifest corrisponde al seguente tipo di messaggio, mostrato qui nel formato di buffer di protocollo:

message ImportManifest {
  // The per-table import manifest.
  message TableManifest {
    // Required. The name of the destination table.
    string table_name = 1;
    // Required. The CSV files to import. This value can be either a filepath or a glob pattern.
    repeated string file_patterns = 2;
    // The schema for a table column.
    message Column {
      // Required for each Column that you specify. The name of the column in the
      // destination table.
      string column_name = 1;
      // Required for each Column that you specify. The type of the column.
      string type_name = 2;
    }
    // Optional. The schema for the table columns.
    repeated Column columns = 3;
  }
  // Required. The TableManifest of the tables to be imported.
  repeated TableManifest tables = 1;

  enum ProtoDialect {
    GOOGLE_STANDARD_SQL = 0;
    POSTGRESQL = 1;
  }
  // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
  ProtoDialect dialect = 2;
}

L'esempio seguente mostra un file manifest per importare tabelle chiamate Albums e Singers in un database dialetto SQL. La tabella Albums utilizza lo schema delle colonne che il job recupera dal database, mentre la tabella Singers utilizza lo schema specificato dal file manifest:

{
  "tables": [
    {
      "table_name": "Albums",
      "file_patterns": [
        "gs://bucket1/Albums_1.csv",
        "gs://bucket1/Albums_2.csv"
      ]
    },
    {
      "table_name": "Singers",
      "file_patterns": [
        "gs://bucket1/Singers*.csv"
      ],
      "columns": [
        {"column_name": "SingerId", "type_name": "INT64"},
        {"column_name": "FirstName", "type_name": "STRING"},
        {"column_name": "LastName", "type_name": "STRING"}
      ]
    }
  ]
}

Passaggio 3: crea la tabella per il database Spanner

Prima di eseguire l'importazione, devi creare le tabelle di destinazione nel database Spanner. Se la tabella Spanner di destinazione ha già uno schema, le colonne specificate nel file manifest devono avere gli stessi tipi di dati delle colonne corrispondenti nello schema della tabella di destinazione.

Ti consigliamo di creare indici secondari, chiavi esterne e flussi di modifiche dopo aver importato i dati in Spanner, non durante la creazione iniziale della tabella. Se la tabella contiene già queste strutture, ti consigliamo di eliminarle e ricrearle dopo l'importazione dei dati.

Passaggio 4: esegui un job di importazione di Dataflow utilizzando gcloud

Per avviare il job di importazione, segui le istruzioni per utilizzare Google Cloud CLI per eseguire un job con il modello Cloud Storage Text to Spanner.

Dopo aver avviato un job di importazione, puoi visualizzarne i dettagli nella console Google Cloud.

Al termine del job di importazione, aggiungi eventuali indici secondari, chiavi esterne e flussi di modifiche necessari.

Nota: per evitare addebiti per il trasferimento di dati in uscita, scegli una regione che si sovrapponga alla località del bucket Cloud Storage.

Scegli una regione per il job di importazione

Puoi 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 usufruire dell'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 è a due regioni, puoi usufruire dell'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à bucket Cloud Storage è multiregionale, si applicano i costi per il trasferimento dei dati in uscita. Consulta i prezzi del trasferimento di dati di Cloud Storage per scegliere una regione in cui vengono addebitati 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 o esportazione, puoi visualizzare i dettagli del job, inclusi i log, nella sezione Dataflow della console Google Cloud.

Visualizza dettagli job Dataflow

Per visualizzare i dettagli di eventuali job di importazione/esportazione che hai eseguito nell'ultima settimana, inclusi eventuali job attualmente in esecuzione:

1. Vai alla pagina Panoramica del database per il database.
2. Fai clic sulla voce di menu Importa/Esporta nel riquadro a sinistra. La pagina Importa/Esporta del database mostra un elenco dei job recenti.

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

   

   Nella console Google Cloud vengono visualizzati i dettagli del job Dataflow.

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

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

   Vai alla pagina dei job

2. Trova il job nell'elenco e fai clic sul suo nome.

   Nella console Google Cloud vengono visualizzati i dettagli del job Dataflow.

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).

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 non riesce, cerca gli errori nei log. In caso di errori, il numero di errori viene visualizzato accanto a Log:

Per visualizzare gli errori del job:

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

   Nella console Google Cloud vengono visualizzati i log del job. Potresti dover scorrere per vedere gli errori.

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

3. Fai clic su una singola voce di log per espanderne il contenuto.

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

Risolvere i problemi relativi ai job di importazione o esportazione non riusciti

Se visualizzi i seguenti errori nei log del job:

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 latenza di lettura/scrittura del 99% nella scheda Monitoring del database Spanner nella console Google Cloud. Se mostra valori elevati (più secondi), significa che l'istanza è sovraccarico, causando un timeout e un timeout delle letture/scritture.

Una causa dell'alta latenza è che il job Dataflow viene eseguito utilizzando troppi worker, determinando un carico eccessivo sull'istanza Spanner.

Per specificare un limite al numero di worker Dataflow:

• Se utilizzi la console di Dataflow, il parametro Numero massimo di 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_Text_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 o esportazione a esecuzione lenta

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

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

• Garantisci un numero sufficiente di risorse Dataflow: se le quote di Compute Engine pertinenti limitano le risorse del tuo job Dataflow, nella pagina Dataflow del job nella console Google Cloud vengono visualizzati un'icona di avviso e messaggi di log:

  

  In questo caso, l'aumento delle quote per CPU, indirizzi IP in uso e disco permanente standard potrebbe ridurre il tempo di esecuzione del job, ma potresti incorrere in addebiti più alti di Compute Engine.

• Controlla 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à aggiunge più risorse di Spanner e il job dovrebbe velocizzare il processo, ma ti verranno addebitati ulteriori costi di Spanner.

Fattori che influiscono sulle prestazioni dei job di importazione o esportazione

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

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

• Schema del database Spanner, che include:

  • 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: per buone prestazioni sono necessari worker Dataflow ottimali. Mediante la scalabilità automatica, Dataflow sceglie il numero di worker per il job in base alla quantità di lavoro da svolgere. Il numero di worker sarà tuttavia limitato dalle quote per CPU, indirizzi IP in uso e disco permanente standard. La UI di Dataflow mostra un'icona di avviso in caso di limiti di quota. In questo caso, 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 della CPU significativo su un'istanza Spanner. In genere, un job di esportazione aggiunge un carico leggero su un'istanza Spanner. Se l'istanza ha già un carico esistente considerevole, 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 buone prestazioni di importazione

Quando avvii un job di importazione di Spanner, i worker Dataflow devono essere impostati su un valore ottimale per ottenere buone prestazioni. Troppi worker causino il sovraccarico di Spanner e un numero insufficiente di worker si traduce in prestazioni di importazione insufficienti.

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

Per raggiungere questo 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 con worker n1-standard-2, imposterai il numero massimo di worker su 25, per ottenere 50 vCPU.