Importazione ed esportazione di dati

Anteprima

Questo prodotto o funzionalità è un'offerta in anteprima soggetta ai "Termini delle offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi e può essere utilizzata solo per sviluppare, testare, creare prototipi e dimostrare programmi software. Non può essere utilizzata per l'elaborazione dei dati o per scopi commerciali. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Questo documento descrive come eseguire la migrazione, il backup e il trasferimento dei dati in Spanner Omni utilizzando i formati Avro e CSV. Utilizza la CLI di Spanner Omni per spostare i contenuti del database tra Spanner Omni e soluzioni di archiviazione come Cloud Storage, Amazon Simple Storage Service (Amazon S3), spazio di archiviazione locale compatibile con S3 o file system locali (NFS). I flussi di dati di importazione ed esportazione in Spanner Omni non supportano modelli, gruppi di località o posizionamenti.

Le operazioni di importazione ed esportazione vengono eseguite sui server Spanner Omni e condividono le risorse di sistema disponibili. L'importazione è un'attività che richiede molte risorse e può causare un utilizzo elevato di RAM, CPU e disco, il che potrebbe influire sui carichi di lavoro attivi. Sebbene queste attività vengano in genere eseguite con una priorità inferiore rispetto al traffico normale, ti consigliamo di monitorare il deployment per verificare eventuali impatti sulle prestazioni.

Confronto dei formati file

La tabella seguente confronta le funzionalità dei formati file Avro e CSV per l'importazione e l'esportazione dei dati di Spanner.

Capacità	Avro	CSV
Importa o esporta un intero database	Sì	No
Importa tabelle esportate in precedenza	Sì	Sì
Esporta in un timestamp precedente	Sì	Sì
Importa o esporta utilizzando Spanner	Sì	Sì
Importa dati da altri database	No	Sì

Entrambi i formati Avro e CSV esportano tutte le tabelle del database. Il formato Avro esporta anche lo schema, in modo che tu possa importarlo di nuovo. Il formato CSV non esporta lo schema.

Prima di iniziare

Prima di avviare un'operazione di importazione o esportazione, verifica le autorizzazioni e configura l'accesso alla località di archiviazione dei dati.

Autorizzazioni

Prima di iniziare, assicurati di disporre delle seguenti autorizzazioni:

• spanner.databases.import
• spanner.databases.export

Per saperne di più su Identity and Access Management (IAM) in Spanner Omni, consulta la panoramica di IAM. Per scoprire come aggiornare i ruoli di un utente, consulta Aggiornare gli utenti.

Origine e destinazione dei dati

Puoi archiviare i dati in un bucket Amazon Simple Storage Service (Amazon S3), in un bucket Cloud Storage, in uno spazio di archiviazione locale compatibile con Amazon S3 (ad esempio MinIO) o in un file system locale (NFS). Se utilizzi un file system locale, assicurati che i dati siano disponibili nello stesso percorso su tutti i server del deployment.

Puoi fornire l'accesso al datastore in due modi:

• Aggiungi spazio di archiviazione esterno al deployment: questo è il metodo preferito se prevedi di riutilizzare un bucket.

• Crea credenziali una tantum: assicurati che queste credenziali durino più a lungo della durata dell'operazione di importazione o esportazione (ad esempio, 48 ore).

Le credenziali devono fornire le autorizzazioni per elencare e leggere gli oggetti nel bucket per le importazioni. Per le esportazioni in Amazon S3, sono necessarie le seguenti autorizzazioni Amazon S3 aggiuntive:

• s3:PutObject
• s3:AbortMultipartUpload
• s3:ListBucketMultipartUploads

Per saperne di più, consulta Autorizzazioni IAM.

Importa file Avro di Spanner

Per importare i dati esportati in precedenza da un altro database Spanner (Spanner o Spanner Omni) in formato Avro, segui questi passaggi.

Prerequisiti per l'importazione di Avro

Prima di iniziare l'importazione di Avro, assicurati che il tuo ambiente soddisfi i seguenti requisiti:

• Hai creato il database di destinazione.

• Gli oggetti dello schema che stai importando non esistono già nel database. La procedura di importazione di Avro crea queste tabelle prima di importare i dati.

Istruzioni per l'importazione di Avro

Identifica il percorso della cartella contenente i dati esportati. La cartella contiene:

• Un file spanner-export.json.

• Un file ENTITY_NAME-manifest.json per ogni entità esportata (ad esempio una tabella, una sequenza o uno schema).

• Tutti i file Avro elencati nei file manifest.

Se hai già aggiunto il datastore come spazio di archiviazione esterno, non devi includere le credenziali nel percorso. Puoi fornire il percorso direttamente. Se utilizzi credenziali una tantum, utilizza i seguenti formati URL:

• Cloud Storage: gs://BUCKET_NAME/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY]. Utilizza le credenziali HMAC. Per saperne di più, consulta Chiavi HMAC.

• Amazon S3: s3://S3_BUCKET/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY[&sessiontoken=SESSION_TOKEN]]

• Cartella di file locali*: file:///PATH_TO_DIR

Per avviare l'importazione, esegui questo comando:

spanner databases import DATABASE_ID --url="URL" --format=avro [--avro-skip-wait-for-index-creation]

Note aggiuntive

Tieni presente le seguenti informazioni quando importi file Avro:

• Una nota sull'importazione di colonne generate e modifiche in tempo reale nella documentazione di Spanner.

• Una nota sull'importazione di sequenze nella documentazione di Spanner.

• Una nota sull'importazione di tabelle interleaved e chiavi esterne nella documentazione di Spanner.

• Per saltare l'importazione di entità specifiche, rimuovile dal file spanner-export.json.

• La creazione di indici può richiedere molto tempo per i set di dati di grandi dimensioni. Per evitare di attendere la creazione dell'indice, utilizza il flag facoltativo --avro-skip-wait-for-index-creation.

Quando l'operazione di importazione viene avviata correttamente, restituisce un ID operazione a lunga esecuzione. Utilizza questo ID per monitorare lo stato dell'operazione.

Importa file CSV

Per importare i dati di testo esportati da un altro database, segui questi passaggi.

Prerequisiti per l'importazione di CSV

Prima di iniziare l'importazione di CSV, assicurati di:

• Assicurati che le tabelle siano in uno dei seguenti tipi di dati supportati: BOOL, INT64, FLOAT64, NUMERIC, STRING, DATE, TIMESTAMP, BYTES e JSON.

• Crea il database di destinazione.

• Crea tutte le tabelle in cui vuoi importare i dati. La procedura di importazione di CSV non crea tabelle.

• Assicurati che il file CSV non contenga una riga di intestazione.

Istruzioni per l'importazione di CSV

Per importare file CSV, crea un file manifest che descriva i dati da importare. Il file manifest utilizza la seguente struttura, definita qui in formato protobuf:

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 path 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;
}

Di seguito è riportato un esempio di 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"}
      ]
    }
  ]
}

L'URL nel seguente comando di importazione Il file CSV non contiene una riga di intestazione deve rimandare alla cartella contenente un file manifest in formato JSON, come descritto nell'esempio di manifest. Questo file può essere presente in Cloud Storage, Amazon S3 o in una cartella di file locali, utilizzando lo stesso formato URL per le credenziali descritto nelle istruzioni per l'importazione di Avro. Per avviare l'importazione, esegui questo comando:

spanner databases import DATABASE_ID --url="URL" --format=csv

Opzioni di importazione di CSV

Utilizza i seguenti flag per personalizzare la modalità di gestione dei file di testo da parte di Spanner Omni:

• --csv-date-format: sostituisce il formato delle colonne di data. Il valore predefinito è %Y-%m-%d. Esempio: %d/%m/%Y.

• --csv-timestamp-format: sostituisce il formato delle colonne di timestamp. Utilizza questa opzione solo se Spanner Omni non supporta il formato nel file CSV. Esempio: %d/%m/%Y %H:%M:%S%Ez.

• --csv-delimiter: sostituisce il carattere di delimitazione. Il valore predefinito è una virgola.

• --csv-quote-char: sostituisce il carattere di virgolette. Il valore predefinito è un doppio virgolette.

• --csv-escape-char: sostituisce il carattere di escape. Il valore predefinito è un doppio virgolette.

• --csv-null-string: sostituisce la stringa che rappresenta i valori NULL. Il valore predefinito è \N.

• --csv-has-trailing-delimiters: specifica se i file CSV hanno delimitatori finali. Il valore predefinito è false.

Esporta in file Avro

Per esportare i dati in file Avro, segui le istruzioni relative al formato URL nelle istruzioni per l'importazione di Avro.

Qualsiasi server del deployment può scrivere dati nel datastore fornito. Se utilizzi una cartella di file locali come destinazione, assicurati che tutti i server abbiano accesso allo stesso percorso e possano scriverci in parallelo.

Il sistema esporta tutte le tabelle e le entità del database. Assicurati di fornire un percorso di cartella nuovo e vuoto per i dati esportati.

Per avviare l'esportazione, esegui questo comando:

spanner databases export DATABASE_ID --url="URL" --format=avro

Le esportazioni CSV supportano solo le tabelle e non esportano lo schema del database.

Esporta in file CSV

Le esportazioni CSV non esportano lo schema del database e supportano solo le tabelle. Per esportare i dati in file CSV, esegui questo comando:

spanner databases export DATABASE_ID --url="URL" --format=csv

Risoluzione dei problemi

Se un'importazione non va a buon fine, gli aggiornamenti dello schema e i dati importati non vengono ripristinati automaticamente. Pulisci manualmente il database prima di riprovare a eseguire l'operazione.

La velocità di un'operazione di importazione dipende da diversi fattori, tra cui il numero di file nella cartella, le risorse di calcolo disponibili nel deployment e la velocità del disco. Se sono disponibili risorse sufficienti, il sistema importa i file in parallelo.