Importare ed esportare dati in formato CSV

Questa pagina descrive come esportare i dati da Spanner in file CSV o importare i dati da file CSV nei database con dialetto GoogleSQL o PostgreSQL di Spanner.

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

La procedura utilizza Dataflow. Puoi esportare i dati da Spanner in un bucket Cloud Storage oppure importarli in Spanner da un bucket Cloud Storage contenente un file manifest JSON e un insieme di file CSV.

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

Prima di iniziare

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

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

Abilita le API

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

Requisiti di quota

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

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

• Compute Engine: prima di eseguire il job di importazione o esportazione, devi configurare le quote iniziali per Compute Engine, che Dataflow utilizza. Queste quote rappresentano il numero massimo di risorse che consenti a Dataflow di utilizzare per il tuo job. I valori iniziali consigliati sono:

  • CPU: 200
  • Indirizzi IP in uso: 200
  • Standard Persistent Disk: 50 TB

  In genere, non devi apportare altre modifiche. Dataflow fornisce la scalabilità automatica in modo da pagare solo le risorse effettivamente utilizzate durante l'importazione o l'esportazione. Se il job può utilizzare più risorse, l'interfaccia utente di Dataflow mostra un'icona di avviso. Il job dovrebbe essere completato anche se è presente un'icona di avviso.

Ruoli obbligatori

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

• Visualizzatore Cloud Spanner (roles/spanner.viewer)
• Dataflow Worker (roles/dataflow.worker)
• Storage Admin (roles/storage.admin)
• Lettore database Spanner (roles/spanner.databaseReader)
• Amministratore database (roles/spanner.databaseAdmin)

Nota: il ruolo Amministratore database Spanner è obbligatorio 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 Spanner to Cloud Storage Text.

Puoi anche fare riferimento alle informazioni in questa pagina su l'ottimizzazione dei job lenti e sui fattori che influiscono sulle prestazioni dei job.

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

Importare dati da file CSV in Spanner

La procedura per importare i dati da file CSV include 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 alle colonne corrispondenti nelle tabelle esistenti.
4. Esegui il job di importazione.

Nota: il modello Dataflow non è in grado di gestire un file CSV con intestazioni.

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

La procedura 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.

Tieni presente quanto segue quando esporti i dati:

• 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 devi includere o generare metadati quando esporti i file CSV.

• Non devi seguire alcuna convenzione di denominazione specifica 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 anche creare un file manifest con una descrizione JSON dei file da importare e inserirlo nello stesso bucket Cloud Storage in cui hai archiviato i file CSV. Questo file manifest contiene un array tables che elenca il nome e le posizioni dei file di dati per ogni tabella. Il file specifica anche il dialetto del database di ricezione. Se il dialetto viene omesso, il valore predefinito è GoogleSQL.

Nota: se una tabella ha colonne generate, il 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 generate vengono calcolati automaticamente durante l'importazione.

Il formato del file manifest corrisponde al seguente tipo di messaggio, mostrato qui in formato 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 l'importazione delle tabelle denominate Albums e Singers in un database con dialetto GoogleSQL. 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 stream di modifiche dopo aver importato i dati in Spanner, non quando crei inizialmente la tabella. Se la tabella contiene già queste strutture, ti consigliamo di eliminarle e ricrearle dopo aver importato i dati.

Passaggio 4: esegui un job di importazione 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 visualizzare i dettagli del job nella console Google Cloud .

Al termine del job di importazione, aggiungi gli indici secondari, chiavi esterne e gli stream di modifiche in tempo reale necessari.

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

Scegliere 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 usufruire dell'utilizzo senza costi della rete scegliendo la stessa regione per il job di importazione, a condizione che la regione sia disponibile.

• Se la località del bucket Cloud Storage è a due regioni, puoi usufruire dell'utilizzo senza costi della rete scegliendo una delle due regioni che compongono la località a due regioni per il job di importazione, a condizione che una delle regioni sia disponibile.

• Se una regione in co-location non è disponibile per il job di importazione o se la località del bucket Cloud Storage è una multi-regione, vengono applicati addebiti per il trasferimento di dati in uscita. Consulta i prezzi del trasferimento di dati di Cloud Storage per scegliere una regione che comporti gli addebiti per il trasferimento di dati più bassi.

Visualizzare o risolvere i problemi relativi ai 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 Google Cloud console.

Visualizzare i dettagli del job Dataflow

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

1. Vai alla pagina Panoramica database del database.
2. Fai clic sulla voce di menu del riquadro a sinistra Importa/Esporta. 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:

   

   La Google Cloud console mostra i dettagli del job Dataflow.

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

1. Vai alla pagina Job Dataflow nella Google Cloud console.

   Vai a Job

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

   La Google Cloud console mostra 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 Ora di inizio o Ora di fine.

Visualizzare i log di Dataflow per il job

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

Se un job non riesce, cerca gli errori nei log. Se sono presenti errori, il conteggio degli errori viene visualizzato accanto a Log:

Per visualizzare gli errori del job:

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

   La Google Cloud console 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 espanderne i contenuti.

Per ulteriori informazioni sulla risoluzione dei problemi relativi ai job Dataflow, consulta Risolvere i problemi relativi alla pipeline.

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

Se visualizzi i seguenti errori nei log dei 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 Monitoraggio del database Spanner nella Google Cloud console. Se mostra valori elevati (più secondi), allora significa che l'istanza è sovraccarica, causando il timeout e l'errore delle operazioni di lettura/scrittura.

Una delle cause dell'elevata latenza è che il job Dataflow viene eseguito utilizzando un numero eccessivo di worker, che esercitano un carico eccessivo sull'istanza Spanner.

Per specificare un limite per il numero di worker Dataflow:

Console

Se utilizzi la console Dataflow, il parametro Worker massimi si trova nella sezione Parametri facoltativi della pagina Crea job da modello.

Vai a Dataflow

gcloud

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

Risolvere i problemi relativi agli 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 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 la località 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 di Compute Engine pertinenti limitano le risorse del job Dataflow, la pagina Dataflow del job nella Google Cloud console mostra un'icona di avviso e messaggi di log:

  

  In questa situazione, l'aumento delle quote per CPU, indirizzi IP in uso e Standard Persistent Disk potrebbe ridurre il tempo di esecuzione del job, ma potresti incorrere in addebiti maggiori di Compute Engine.

• Controlla l'utilizzo della CPU di Spanner: se l'utilizzo della CPU per l'istanza è superiore al 65%, puoi aumentare la capacità di calcolo in quell'istanza. La capacità aggiunge altre risorse Spanner e il job dovrebbe accelerare, ma incorrerai in addebiti maggiori di Spanner.

Fattori che influiscono sulle prestazioni dei job di importazione o esportazione

Diversi fattori influenzano il tempo necessario per completare un job di importazione o esportazione.

• Dimensioni del database 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 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 le regioni rallenta il job.

• Numero di worker Dataflow: i worker Dataflow ottimali sono necessari per prestazioni ottimali. Utilizzando la scalabilità automatica, Dataflow sceglie il numero di worker per il job in base alla quantità di lavoro da svolgere. Il numero di worker, tuttavia, sarà limitato dalle quote per CPU, indirizzi IP in uso e Standard Persistent Disk. 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 di CPU significativo a un'istanza Spanner. Un job di esportazione in genere aggiunge un carico leggero a 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.

Ottimizzare i worker per prestazioni di importazione ottimali

Quando avvii un job di importazione Spanner, i worker Dataflow devono essere impostati su un valore ottimale per prestazioni ottimali. Un numero eccessivo di worker sovraccarica Spanner, mentre un numero insufficiente di worker comporta prestazioni di importazione deludenti.

Il numero massimo di worker dipende in gran parte 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 l'efficienza di Spanner e il completamento del job senza errori.

Per raggiungere questo target di utilizzo nella maggior parte degli schemi e degli scenari, ti 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, imposteresti il numero massimo di worker su 25, ottenendo 50 vCPU.