Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Importer et exporter des données

Ce document explique comment migrer, sauvegarder et transférer des données dans Spanner Omni à l'aide des formats Avro et CSV. Utilisez l'interface de ligne de commande Spanner Omni pour déplacer le contenu de la base de données entre Spanner Omni et des solutions de stockage telles que Cloud Storage, Amazon Simple Storage Service (Amazon S3), le stockage local compatible avec S3 ou les systèmes de fichiers locaux (NFS). Les flux de données d'importation et d'exportation dans Spanner Omni ne sont pas compatibles avec les modèles, les groupes de localité ni les emplacements.

Les opérations d'importation et d'exportation s'exécutent sur des serveurs Spanner Omni et partagent les ressources système disponibles. L'importation nécessite beaucoup de ressources et peut entraîner une utilisation élevée de la RAM, du processeur et du disque, ce qui peut affecter les charges de travail actives. Bien que ces tâches s'exécutent généralement à une priorité inférieure à celle du trafic normal, vous devez surveiller votre déploiement pour détecter tout impact potentiel sur les performances.

Comparaison des formats de fichiers

Le tableau suivant compare les fonctionnalités des formats de fichier Avro et CSV pour l'importation et l'exportation de données Spanner.

Capacité	Avro	CSV
Importer ou exporter une base de données entière	Oui	Non
Importer des tableaux précédemment exportés	Oui	Oui
Exporter à un code temporel passé	Oui	Oui
Importer ou exporter des données à l'aide de Spanner	Oui	Oui
Importer des données depuis d'autres bases de données	Non	Oui

Les formats Avro et CSV exportent toutes les tables de la base de données. Le format Avro exporte également le schéma, ce qui vous permet de l'importer à nouveau. Le format CSV n'exporte pas le schéma.

Avant de commencer

Avant de lancer une opération d'importation ou d'exportation, vérifiez vos autorisations et configurez l'accès à l'emplacement de stockage de vos données.

Autorisations

Avant de commencer, assurez-vous de disposer des autorisations suivantes :

spanner.databases.import
spanner.databases.export

Pour en savoir plus sur Identity and Access Management (IAM) dans Spanner Omni, consultez la présentation d'IAM. Pour savoir comment modifier les rôles d'un utilisateur, consultez Modifier des utilisateurs.

Source et destination des données

Vous pouvez stocker des données dans un bucket Amazon Simple Storage Service (Amazon S3), un bucket Cloud Storage, un stockage local compatible avec Amazon S3 (tel que MinIO) ou un système de fichiers local (NFS). Si vous utilisez un système de fichiers local, assurez-vous que les données sont disponibles au même chemin d'accès sur tous les serveurs du déploiement.

Vous pouvez fournir un accès au datastore de deux manières :

Ajoutez un stockage externe au déploiement : il s'agit de la méthode recommandée si vous prévoyez de réutiliser un bucket.
Créez des identifiants ponctuels : assurez-vous qu'ils durent plus longtemps que l'opération d'importation ou d'exportation (par exemple, 48 heures).

Les identifiants doivent fournir les autorisations nécessaires pour lister et lire les objets du bucket pour les importations. Pour les exportations vers Amazon S3, vous avez besoin des autorisations Amazon S3 supplémentaires suivantes :

s3:PutObject
s3:AbortMultipartUpload
s3:ListBucketMultipartUploads

Pour en savoir plus, consultez Autorisations IAM.

Importer des fichiers Avro Spanner

Pour importer des données que vous avez précédemment exportées d'une autre base de données Spanner (Spanner ou Spanner Omni) au format Avro, procédez comme suit.

Conditions requises pour l'importation Avro

Avant de commencer l'importation Avro, assurez-vous que votre environnement répond aux exigences suivantes :

Vous avez créé la base de données de destination.
Les objets de schéma que vous importez n'existent pas encore dans la base de données. Le processus d'importation Avro crée ces tables avant d'importer les données.

Instructions d'importation Avro

Identifiez le chemin d'accès au dossier contenant les données exportées. Le dossier contient les éléments suivants :

Un fichier spanner-export.json.
Un fichier ENTITY_NAME-manifest.json pour chaque entité exportée (table, séquence ou schéma, par exemple).
Tous les fichiers Avro listés dans les fichiers manifestes.

Si vous avez déjà ajouté le datastore en tant que stockage externe, vous n'avez pas besoin d'inclure les identifiants dans le chemin d'accès. Vous pouvez fournir le chemin d'accès directement. Si vous utilisez des identifiants à usage unique, utilisez les formats d'URL suivants :

Cloud Storage : gs://BUCKET_NAME/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY]. Utilisez des identifiants HMAC. Pour en savoir plus, consultez Clés HMAC.
Amazon S3 : s3://S3_BUCKET/BASE_FOLDER[?accesskey=ACCESS_KEY&secret=SECRET_KEY[&sessiontoken=SESSION_TOKEN]]
Dossier de fichiers locaux*: file:///PATH_TO_DIR

Pour démarrer l'importation, exécutez la commande suivante :

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

Remarques supplémentaires

Tenez compte des informations suivantes lorsque vous importez des fichiers Avro :

Remarque sur l'importation de colonnes générées et de flux de modifications dans la documentation Spanner.
Remarque sur l'importation de séquences dans la documentation Spanner.
Remarque sur l'importation de tables entrelacées et de clés étrangères dans la documentation Spanner.
Pour ne pas importer certaines entités, supprimez-les du fichier spanner-export.json.
La création d'index peut prendre un certain temps pour les grands ensembles de données. Pour ne pas attendre la création de l'index, utilisez l'option facultative --avro-skip-wait-for-index-creation.

Lorsque l'opération d'importation démarre correctement, elle renvoie un ID d'opération de longue durée. Utilisez cet ID pour suivre l'état de l'opération.

Importer des fichiers CSV

Pour importer des données textuelles que vous avez exportées depuis une autre base de données, procédez comme suit.

Conditions préalables à l'importation de fichiers CSV

Avant d'importer le fichier CSV, assurez-vous d'effectuer les opérations suivantes :

Assurez-vous que vos tableaux utilisent l'un des types de données compatibles suivants : BOOL, INT64, FLOAT64, NUMERIC, STRING, DATE, TIMESTAMP, BYTES et JSON.
Créez la base de données de destination.
Créez toutes les tables dans lesquelles vous souhaitez importer des données. Le processus d'importation de fichiers CSV ne crée pas de tables.
Assurez-vous que le fichier CSV ne contient pas de ligne d'en-tête.

Instructions pour l'importation de fichiers CSV

Pour importer des fichiers CSV, créez un fichier manifeste qui décrit les données à importer. Le fichier manifeste utilise la structure suivante, définie ici au format 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;
}

Voici un exemple de fichier manifeste :

{
  "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 de la commande import dans l'exemple suivant doit pointer vers le dossier contenant un fichier manifeste au format JSON, comme décrit dans l'exemple de fichier manifeste. Ce fichier peut se trouver dans Cloud Storage, Amazon S3 ou un dossier de fichiers local. Il utilise le même format d'URL pour les identifiants que celui décrit dans les instructions d'importation Avro. Pour lancer l'importation, exécutez la commande suivante :

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

Options d'importation CSV

Utilisez les indicateurs suivants pour personnaliser la façon dont Spanner Omni gère les fichiers texte :

--csv-date-format : remplace le format des colonnes de date. La valeur par défaut est %Y-%m-%d. Exemple : %d/%m/%Y.
--csv-timestamp-format : remplace le format des colonnes d'horodatage. N'utilisez cette option que si Spanner Omni n'est pas compatible avec le format du fichier CSV. Exemple : %d/%m/%Y %H:%M:%S%Ez.
--csv-delimiter : remplace le caractère délimiteur. La valeur par défaut est une virgule.
--csv-quote-char : remplace le caractère de guillemet. La valeur par défaut est une double guillemet.
--csv-escape-char : remplace le caractère d'échappement. La valeur par défaut est une double guillemet.
--csv-null-string : remplace la chaîne qui représente les valeurs NULL. La valeur par défaut est \N.
--csv-has-trailing-delimiters : indique si les fichiers CSV contiennent des délimiteurs de fin. La valeur par défaut est false.

Exporter vers des fichiers Avro

Pour exporter des données vers des fichiers Avro, suivez les instructions de format d'URL dans les instructions d'importation Avro.

N'importe quel serveur du déploiement peut écrire des données dans le datastore fourni. Si vous utilisez un dossier de fichiers local comme destination, assurez-vous que tous les serveurs ont accès au même chemin d'accès et peuvent y écrire en parallèle.

Le système exporte toutes les tables et entités de la base de données. Assurez-vous de fournir un chemin d'accès à un nouveau dossier vide pour les données exportées.

Pour lancer l'exportation, exécutez la commande suivante :

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

Les exportations CSV ne sont compatibles qu'avec les tables et n'exportent pas le schéma de la base de données.

Exporter vers des fichiers CSV

Les exportations CSV n'exportent pas le schéma de base de données et ne prennent en charge que les tables. Pour exporter des données vers des fichiers CSV, exécutez la commande suivante :

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

Dépannage

Si une importation échoue, les mises à jour du schéma et les données importées ne sont pas automatiquement annulées. Nettoyez manuellement la base de données avant de réessayer l'opération.

La vitesse d'une opération d'importation dépend de plusieurs facteurs, y compris du nombre de fichiers dans le dossier, des ressources de calcul disponibles dans le déploiement et de la vitesse du disque. Si suffisamment de ressources sont disponibles, le système importe les fichiers en parallèle.

Importer et exporter des données Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.