Importer et exporter des données

Aperçu

Ce produit ou cette fonctionnalité est une offre en avant-première soumise aux "Conditions des offres de pré-DG" de la section Conditions générales du service des conditions spécifiques au service. Il ne peut être utilisé qu'à des fins de développement, de test, de prototypage et de démonstration de logiciels. Il ne peut pas être utilisé à des fins de traitement des données ni à des fins commerciales. Les produits et fonctionnalités de pré-DG sont proposés "en l'état" et peuvent présenter une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

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 transférer 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és 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 avec 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 fichier

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 tables précédemment exportées	Oui	Oui
Exporter à un horodatage antérieur	Oui	Oui
Importer ou exporter des données à l'aide de Spanner	Oui	Oui
Importer des données à partir 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 à votre emplacement de stockage de 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 l'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 pour l'importation Avro

Identifiez le chemin d'accès au dossier contenant les données exportées. Ce 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 lancer 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'un index peut prendre un certain temps pour les grands ensembles de données. Pour éviter d'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, veillez à effectuer les actions suivantes :

• Assurez-vous que vos tables utilisent l'un des types de données compatibles suivants : BOOL, INT64, FLOAT64, NUMERIC, STRING, DATE, TIMESTAMP, BYTES et JSON.

• Créez une 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 d'importation 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 suivante doit pointer vers le dossier contenant un fichier manifeste au format JSON, comme décrit dans l'exemple de fichier manifeste. Ce fichier peut être situé dans Cloud Storage, Amazon S3 ou un dossier de fichiers local, en utilisant 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 de délimitation. La valeur par défaut est une virgule.

• --csv-quote-char : remplace le caractère de guillemet. La valeur par défaut est un guillemet double.

• --csv-escape-char : remplace le caractère d'échappement. La valeur par défaut est un guillemet double.

• --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 comportent 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 relatives au 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 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 que le schéma de la base de données et les tables d'assistance. 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.