Importazione ed esportazione di dati in formato CSV

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

La procedura utilizza Dataflow. Puoi esportare i dati da Spanner in un bucket Cloud Storage oppure puoi importare i dati in Spanner da un bucket Cloud Storage che contiene un file JSON e un insieme di file CSV.

Prima di iniziare

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

Abilita le API

Devi anche avere una quota sufficiente e le 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 in base alla quantità di dati che importi. Nessun altro capacità di calcolo necessaria per importare o esportare 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 Ottimizzare le offerte di lavoro.
  • Cloud Storage: per eseguire l'importazione, devi avere un bucket contenenti 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 una dimensione per il bucket.
  • Dataflow: i job di importazione o esportazione sono soggetti alla stessa CPU, utilizzo del disco e indirizzo IP quote di Compute Engine come e altri job Dataflow.

  • Compute Engine: prima di eseguire il job di importazione o esportazione, 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 offre scalabilità automatica, in modo da pagare solo e le risorse effettive utilizzate durante l'importazione o l'esportazione. 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.

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'importazione o esportazione un lavoro. Per informazioni sulla concessione di ruoli e autorizzazioni, consulta Applica i ruoli IAM.

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

Esporta i dati di Spanner in file CSV

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

È inoltre possibile consultare le informazioni contenute in questo documento la visualizzazione o la risoluzione dei problemi dei job, ottimizzando i job lenti e fattori che influiscono sulle prestazioni del job.

Importa dati da file CSV in Spanner

La procedura per importare i dati dai 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 corrispondono 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 da file CSV che si trovano in un nel bucket Cloud Storage. Puoi esportare i dati in formato CSV da qualsiasi sorgente.

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 il file CSV .

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

Se non esporti i file direttamente in Cloud Storage, devi: carica 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 il file CSV . Questo file manifest contiene un array tables che elenca il nome e i dati le posizioni dei file per ogni tabella. Il file specifica anche il dialetto del database di destinazione. Se il dialetto viene omesso, il valore predefinito sarà GoogleSQL.

Il formato del file manifest corrisponde al seguente tipo di messaggio, mostrato qui in formato del 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 di tabelle denominato Albums e Singers in un database di dialetti GoogleSQL. La tabella Albums utilizza lo schema delle colonne recuperato dal job dal database e la tabella Singers utilizza lo schema utilizzato dal file manifest specifica: 

{
  "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 il database Spanner. Se la tabella Spanner di destinazione ha già un tutte le colonne specificate nel file manifest devono avere gli stessi dati come colonne corrispondenti nello schema della tabella di destinazione.

Ti consigliamo di creare indici secondari, chiavi esterne e modificare flussi di dati dopo l'importazione dei dati in Spanner, non quando creiamo inizialmente la tabella. Se la tabella li contiene già di strutture, ti consigliamo di rilasciarle e ricrearle dopo importi i tuoi dati.

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

Per avviare il job di importazione, segui le istruzioni per l'utilizzo di Google Cloud CLI per eseguire un job con il modello di testo Cloud Storage in 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 eventuali indici secondari necessari, chiavi esterne e flussi di modifiche.

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. Da evitare addebiti per il trasferimento di dati in uscita, scegli una regione corrisponde alla località del bucket Cloud Storage.

  • Se la località del bucket Cloud Storage è in una regione, possono sfruttare l'utilizzo gratuito della rete scegliendo la stessa regione per il job di importazione, supponendo che la 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 le tue La località del bucket Cloud Storage è multiregionale, 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 o esportazione, puoi visualizzare i dettagli del job, tra cui 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:

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

    Messaggio di stato del job in corso

    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 alla pagina dei job

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

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

Visualizza i log di Dataflow per il tuo job

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

Se un job ha esito negativo, cerca gli errori nei log. Se ci sono errori, l'errore il conteggio delle voci viene visualizzato accanto a Log:

Esempio di conteggio degli errori accanto al pulsante Log

Per visualizzare gli errori del job:

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

    La console Google Cloud visualizza i log del job. Potresti dover scorri per vedere 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 il contenuto.

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

Risolvere i problemi relativi ai job di importazione o esportazione 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 la latenza di lettura/scrittura del 99% nella Monitoring del tuo database Spanner nella nella console Google Cloud. Se mostra valori elevati (più secondi), indica che l'istanza è sovraccarica, causando legge/scrive in timeout e non riesce.

Una causa della latenza elevata è che il job Dataflow è in esecuzione utilizzando troppe dei worker, applicando un carico eccessivo all'istanza Spanner.

Per specificare un limite al numero di worker Dataflow:

  • Se utilizzi la console Dataflow, il parametro Max worker è che 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 con esecuzione lenta

Se hai seguito i suggerimenti nelle impostazioni iniziali, dovresti in genere non devono essere apportate altre modifiche. Se il job è lento, puoi provare altre ottimizzazioni:

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

  • Garantire risorse Dataflow sufficienti: se quote di Compute Engine pertinenti limitare le risorse del job Dataflow, Pagina Dataflow nella console Google Cloud mostra un'icona di avviso Icona di avviso e registra messaggi:

    Screenshot dell'avviso relativo al limite di quota

    In questa situazione, aumentando le quote CPU, indirizzi IP in uso e disco permanente standard potrebbero ridurre del job, ma potresti incorrere in tempi addebiti.

  • Controlla l'utilizzo della CPU di Spanner: se noti che la CPU per l'istanza è superiore al 65%, puoi aumentare la capacità di calcolo dell'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 sulle prestazioni del job di importazione o esportazione

Il tempo necessario per completare un job di importazione o esportazione è influenzato 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

  • 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 nello stesso regione, lo spostamento dei dati tra regioni rallenta il job.

  • Numero di worker Dataflow: Dataflow ottimale sono necessari per ottenere buone prestazioni. Con la scalabilità automatica, Dataflow sceglie il numero di worker per del lavoro 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 avviso se riscontra limiti di quota. In questa situazione, l'avanzamento è più lento, ma dovrebbe comunque essere completato. La scalabilità automatica può sovraccaricare Spanner causando errori in presenza di grandi quantità di dati da importare.

  • Carico esistente su Spanner: un job di importazione aggiunge sulla CPU per un'istanza Spanner. In genere un job di esportazione aggiunge un carico leggero su un oggetto Spanner in esecuzione in un'istanza Compute Engine. 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.

Ottimizza i worker per ottenere buone prestazioni di 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 sovraccarica Spanner e un numero troppo basso di worker si traduce in un problema le prestazioni di importazione.

Il numero massimo di worker dipende fortemente dalla dimensione dei dati, ma idealmente, l'utilizzo totale della CPU da parte di Spanner dovrebbe essere compreso tra dal 70% al 90%. Questo offre un buon equilibrio tra Spanner dell'efficienza e del completamento dei job senza errori.

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

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