Importer et exporter des données au format CSV

Cette page explique comment exporter des données de Spanner vers des fichiers CSV ou les importer des fichiers CSV dans une base de données Spanner.

• Si vous souhaitez importer une base de données Spanner que vous avez précédemment exportée aux fichiers Avro dans Cloud Storage, consultez Importez des fichiers Spanner Avro.
• Si vous souhaitez importer des fichiers Avro à partir d'une base de données autre que Spanner, consultez la page Importer des données à partir de bases de données autres que Spanner.

Le processus utilise Dataflow. Vous pouvez exporter des données de Spanner vers un bucket Cloud Storage, ou importer des données dans Spanner à partir d'un bucket Cloud Storage contenant un fichier manifeste JSON et un ensemble de fichiers CSV.

Remarque : Pour découvrir Spanner à l'aide d'une instance d'essai gratuit de 90 jours, consultez Créer une instance d'essai gratuit Spanner.

Avant de commencer

Pour importer ou exporter une base de données Spanner, vous devez d'abord activer les API Spanner, Cloud Storage, Compute Engine et Dataflow :

Enable the APIs

Vous devez également disposer d'un quota suffisant, ainsi que des autorisations IAM requises.

Exigences en matière de quota

Voici les exigences de quota concernant les tâches d'importation ou d'exportation :

• Spanner: vous devez disposer d'une capacité de calcul suffisante pour prendre en charge la quantité de données que vous importez. Aucune capacité de calcul supplémentaire n'est requise pour importer ou exporter une base de données, mais il peut s'avérer nécessaire d'ajouter de la capacité de calcul pour que la tâche se termine dans un délai raisonnable. Pour en savoir plus, consultez la section Optimiser les tâches.
• Cloud Storage : pour effectuer des importations, vous devez disposer d'un bucket contenant les fichiers que vous avez exportés auparavant. Pour procéder à l'exportation, vous devez créer un bucket pour vos fichiers exportés si : vous n'en avez pas encore. Vous pouvez le faire dans la console Google Cloud, soit via la page Cloud Storage, soit lors de la création de votre exportation sur la page Spanner. Vous n'avez pas besoin de définir une taille pour votre bucket.
• Dataflow : les tâches d'importation ou d'exportation sont soumises aux mêmes exigences que les autres tâches Dataflow en ce qui concerne les quotas Compute Engine, aussi bien pour l'utilisation de processeurs et d'espace disque que pour le nombre d'adresses IP.

• Compute Engine : avant d'exécuter une tâche d'importation ou d'exportation, vous devez définir les quotas initiaux Compute Engine utilisés par Dataflow. Ces quotas représentent le nombre maximal de ressources que vous permettez à Dataflow d'utiliser pour votre tâche. Les valeurs de départ recommandées sont les suivantes :

  • Processeurs : 200
  • Adresses IP en cours d'utilisation : 200
  • Disque persistant standard : 50 To

  En règle générale, vous n'avez aucun autre ajustement à effectuer. Dataflow gère l'autoscaling de sorte que vous n'ayez à payer que pour les ressources effectivement utilisées lors de l'importation ou de l'exportation. S'il apparaît que votre tâche pourrait utiliser davantage de ressources, l'interface utilisateur de Dataflow affiche une icône d'avertissement, mais cela n'empêche normalement pas la tâche d'aboutir.

Rôles requis

Pour obtenir les autorisations nécessaires pour exporter une base de données, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le compte de service de l'agent Dataflow :

• Lecteur Cloud Spanner (roles/spanner.viewer)
• Nœud de calcul Dataflow (roles/dataflow.worker)
• Administrateur de l'espace de stockage (roles/storage.admin)
• Lecteur de bases de données Spanner (roles/spanner.databaseReader)
• Administrateur de base de données (roles/spanner.databaseAdmin)

Remarque : Le rôle Administrateur de bases de données Spanner n'est requis que pour les tâches d'importation.

Exporter des données Spanner vers des fichiers CSV

Pour exporter des données de Spanner vers des fichiers CSV dans Cloud Storage, suivez les instructions permettant d'utiliser la Google Cloud CLI et d'exécuter une tâche avec le modèle Texte Cloud Storage vers Spanner.

Vous pouvez également vous reporter aux informations de ce document concernant l'affichage ou le dépannage des tâches, l'optimisation des tâches lentes et les facteurs affectant les performances des tâches.

Remarque : Les données du flux de modifications ni les valeurs des colonnes générées stockées ne sont pas exportées.

Importer des données à partir de fichiers CSV dans Spanner

Le processus d'importation de données à partir de fichiers CSV comprend les étapes suivantes :

1. Exportez vos données vers des fichiers CSV et stockez ces fichiers dans Cloud Storage. N'incluez pas de ligne d'en-tête.
2. Créez un fichier manifeste JSON et stockez-le avec vos fichiers CSV.
3. Créez des tables cibles vides dans votre base de données Spanner ou assurez-vous que les types de données des colonnes de vos fichiers CSV sont identiques à ceux des colonnes correspondantes dans vos tables existantes.
4. Exécutez votre tâche d'importation.

Remarque :Le modèle de flux de données ne peut pas gérer les fichiers CSV comportant des en-têtes.

Étape 1: Exportez les données d'une base de données autre que Spanner vers des fichiers CSV

Le processus d'importation apporte des données issues de fichiers CSV situés dans un bucket Cloud Storage. Vous pouvez exporter des données au format CSV depuis n'importe quelle source.

Tenez compte des points suivants lorsque vous exportez vos données :

• Les fichiers texte à importer doivent être au format CSV.

• Les données doivent correspondre à l'un des types suivants :

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

• Il n'est pas nécessaire d'inclure ou de générer des métadonnées lorsque vous exportez les fichiers CSV.

• Il n'est pas nécessaire de suivre une convention d'attribution de noms particulière pour vos fichiers.

Si vous n'exportez pas vos fichiers directement vers Cloud Storage, vous devez importer les fichiers CSV dans un bucket Cloud Storage.

Étape 2: Créez un fichier manifeste JSON

Vous devez également créer un fichier manifeste comprenant une description JSON des fichiers à importer et le placer dans le même bucket Cloud Storage que celui dans lequel vous avez stocké vos fichiers CSV. Ce fichier contient un tableau tables qui répertorie le nom et les emplacements des fichiers de données pour chaque table. Le fichier spécifie également le dialecte de la base de données destinataire. Si le dialecte est omis, la valeur GoogleSQL est utilisée par défaut.

Remarque : Si une table contient des colonnes générées, le fichier manifeste doit inclure une liste explicite des colonnes non générées à importer pour cette table. Spanner utilise cette liste pour mapper les colonnes CSV aux colonnes de table appropriées. Les valeurs de colonne générées sont automatiquement calculées lors de l'importation.

Le format du fichier manifeste correspond au type de message suivant, affiché ici au format de tampon de protocole :

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'exemple suivant illustre un fichier manifeste pour l'importation de tables nommées Albums et Singers dans une base de données Google SQL. La table Albums utilise le schéma de la colonne que la tâche extrait de la base de données, et la table Singers utilise le schéma spécifié par le 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"}
      ]
    }
  ]
}

Étape 3: Créez la table pour votre base de données Spanner

Avant d'exécuter votre importation, vous devez créer les tables cibles dans votre base de données Spanner. Si la table Spanner cible possède déjà un toutes les colonnes spécifiées dans le fichier manifeste doivent contenir les mêmes données comme colonnes correspondantes dans le schéma de la table cible.

Nous vous recommandons de créer des index secondaires, des clés étrangères et des flux de modifications après avoir importé vos données dans Spanner, et non lors de la création initiale de la table. Si votre table contient déjà ces structures, nous vous recommandons de les supprimer et de les recréer après avoir importé vos données.

Étape 4 : Exécuter une tâche d'importation Dataflow à l'aide de gcloud

Pour démarrer votre job d'importation, suivez les instructions d'utilisation de la Google Cloud CLI pour exécuter une tâche avec le modèle Cloud Storage Text-to-Spanner.

Après avoir démarré un job d'importation, vous pouvez en consulter les détails dans la console Google Cloud.

Une fois le job d'importation terminé, ajoutez tous les index secondaires nécessaires. des clés étrangères et des flux de modifications.

Remarque : Pour éviter les frais de transfert de données sortantes, choisissez une région qui chevauche l'emplacement de votre bucket Cloud Storage.

Choisir une région pour votre tâche d'importation

Vous pouvez être amené à choisir une région différente selon l'emplacement de votre bucket Cloud Storage. Pour éviter frais de transfert de données sortantes, choisissez une région correspond à l'emplacement de votre bucket Cloud Storage.

• Si l'emplacement de votre bucket Cloud Storage est une région, vous peuvent profiter de l'utilisation gratuite du réseau en choisissant la même région pour votre job d'importation, en supposant que cette région est disponible.

• Si l'emplacement de votre bucket Cloud Storage est une région duale, vous pouvez bénéficier de l'utilisation gratuite du réseau en choisissant l'une des deux régions qui la composent pour votre tâche d'importation, à condition que l'une d'elles soit disponible.

• Si une région colocalisée n'est pas disponible pour votre tâche d'importation ou si l'emplacement de votre bucket Cloud Storage est une région multirégionale, des frais de transfert de données sortants s'appliquent. Consulter Cloud Storage de transfert de données pour choisir une région qui entraîne le les frais de transfert de données les plus bas.

Afficher ou dépanner des tâches dans l'interface utilisateur de Dataflow

Après avoir démarré une tâche d'importation ou d'exportation, vous pouvez en afficher les détails, y compris les journaux, dans la section Dataflow de la console Google Cloud.

Afficher les détails d'une tâche Dataflow

Pour afficher les détails des jobs d'importation ou d'exportation que vous avez exécutés au cours de la semaine précédente, y compris toutes les tâches en cours d'exécution:

1. Accédez à la page Présentation de la base de données correspondant à la base de données.
2. Cliquez sur l'élément de menu du volet Importations/Exportations à gauche. La page Importations/Exportations de la base de données affiche la liste des tâches récentes.

3. Sur la page Importations/Exportations de la base de données, cliquez sur le nom de la tâche dans la colonne Nom de la tâche Dataflow :

   

   La console Google Cloud affiche les détails de Dataflow d'un projet.

Pour afficher une tâche que vous avez exécutée il y a plus d'une semaine :

1. Accédez à la page des tâches Dataflow dans la console Google Cloud.

   Accéder aux tâches

2. Recherchez votre tâche dans la liste, puis cliquez sur son nom.

   La console Google Cloud affiche les détails de Dataflow d'un projet.

Remarque : Les tâches de même type relatives à une même base de données portent toutes le même nom. Vous pouvez les distinguer les unes des autres d'après les valeurs spécifiées dans les colonnes Heure de début ou Heure de fin.

Afficher les journaux Dataflow associés à votre job

Pour afficher les journaux d'une tâche Dataflow, accédez à la page des détails de la tâche, puis cliquez sur Journaux à droite du nom de la tâche.

Si une tâche échoue, recherchez les erreurs dans les journaux. Si des erreurs ont été enregistrées, leur nombre s'affiche à côté du bouton Logs (Journaux) :

Pour afficher les erreurs relatives à une tâche :

1. Cliquez sur le nombre d'erreurs à côté de Journaux.

   La console Google Cloud affiche les journaux de la tâche. Vous devrez éventuellement faire défiler l'affichage pour voir les erreurs.

2. Repérez les entrées signalées par l'icône d'erreur .

3. Cliquez sur une entrée de journal pour développer son contenu.

Pour en savoir plus sur le dépannage lié aux tâches Dataflow, consultez la page Résoudre les problèmes liés à votre pipeline.

Résoudre les problèmes liés aux tâches d'importation ou d'exportation ayant échoué

Si les erreurs suivantes s'affichent dans les journaux de vos tâches :

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Vérifiez la latence de lecture/écriture de 99% dans la l'onglet Surveillance de votre base de données Spanner dans console Google Cloud. S'il affiche des valeurs élevées (plusieurs secondes), alors cela indique que l'instance est surchargée, ce qui entraîne lit/écrit dans et échouer.

Cette latence élevée peut s'expliquer notamment par le fait que la tâche Dataflow s'exécute à l'aide d'un trop grand nombre de nœuds de calcul, ce qui surcharge l'instance Spanner.

Pour spécifier une limite sur le nombre de nœuds de calcul Dataflow:

Console

Si vous utilisez la console Dataflow, la colonne Nombre maximal de nœuds de calcul se trouve dans la section Paramètres facultatifs de la Créer un job à partir d'un modèle.

Accéder à Dataflow

gcloud

Exécutez la gcloud dataflow jobs run. et spécifiez l'argument max-workers. Exemple :

  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

Résoudre une erreur réseau

L'erreur suivante peut se produire lorsque vous exportez vos bases de données Spanner :

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

Cette erreur se produit, car Spanner suppose que vous avez l'intention d'utiliser un réseau VPC en mode automatique nommé default dans le même projet que Job Dataflow. Si vous ne disposez pas d'un réseau VPC par défaut projet ou si votre réseau VPC se trouve dans un réseau VPC en mode personnalisé, vous devez créer un job Dataflow et spécifiez un autre réseau ou sous-réseau.

Optimiser les tâches d'importation ou d'exportation lentes

Si vous avez adopté les paramètres initiaux suggérés plus haut, vous n'avez en principe aucun autre réglage à effectuer. Voici toutefois quelques possibilités d'optimisation supplémentaires à envisager si l'exécution de votre tâche est lente :

• Optimisez l'emplacement de la tâche et des données : exécutez votre tâche Dataflow dans la même région que celle où se trouvent votre instance Spanner et votre bucket Cloud Storage.

• Assurez-vous de disposer de ressources Dataflow suffisantes: si le quotas Compute Engine pertinents limiter les ressources de votre job Dataflow, Page Dataflow dans la console Google Cloud affiche une icône d'avertissement et journal messages:

  

  Dans ce cas, l'augmentation des quotas en termes de processeurs, d'adresses IP en cours d'utilisation et de disques persistants standards peut accélérer l'exécution de votre tâche, mais également augmenter les frais facturés pour Compute Engine.

• Vérifiez l'utilisation du processeur Spanner: si vous constatez que le processeur de l'instance est supérieure à 65%, vous pouvez augmentez la capacité de calcul de cette instance. La capacité ajoute davantage de ressources Spanner et la tâche devrait accélérer, mais vous devrez payer plus de frais pour Spanner.

Facteurs affectant les performances des tâches d'importation ou d'exportation

Plusieurs facteurs influent sur le temps nécessaire pour mener à bien une tâche d'importation ou d'exportation.

• Taille de la base de données Spanner: le traitement de davantage de données prend plus de temps et des ressources.

• Schéma de base de données Spanner, y compris:

  • Nombre de tables
  • Taille des lignes
  • Le nombre d'index secondaires
  • Le nombre de clés étrangères
  • Nombre de flux de modifications

• Emplacement des données: les données sont transférées entre Spanner et Cloud Storage avec Dataflow. Dans l'idéal, ces trois composants doivent se trouver dans la même région. Dans le cas contraire, le déplacement des données entre les régions ralentit l'exécution de la tâche.

• Nombre de nœuds de calcul Dataflow : les nœuds de calcul Dataflow optimaux sont nécessaires pour de bonnes performances. En utilisant l'autoscaling, Dataflow choisit le nombre de nœuds de calcul pour la tâche en fonction de la quantité de travail à effectuer. Le nombre de nœuds de calcul sera toutefois limité par les quotas en matière de processeurs, d'adresses IP en cours d'utilisation et de disques persistants standards. L'interface utilisateur de Dataflow affiche une icône d'avertissement lorsque des limites de quota sont atteintes. Dans ce cas, la progression est ralentie, mais la tâche doit néanmoins aboutir. L'autoscaling peut surcharger Spanner et entraîner des erreurs en cas de une grande quantité de données à importer.

• Charge existante sur Spanner: une tâche d'importation ajoute une charge importante du processeur sur une instance Spanner. Une tâche d'exportation ajoute généralement une faible charge sur une instance Spanner. Si cette instance présentait déjà une charge importante, l'exécution de la tâche est ralentie.

• Quantité de capacité de calcul Spanner : si l'instance présente un taux d'utilisation du processeur supérieur à 65 %, l'exécution de la tâche est ralentie.

Régler les nœuds de calcul afin d'obtenir de bonnes performances pour l'importation

Lorsque vous démarrez une tâche d'importation Spanner, les nœuds de calcul Dataflow doivent être définis sur une valeur optimale pour optimiser les performances. Un trop grand nombre de nœuds de calcul peut surcharger Spanner, et un nombre trop faible de nœuds de calcul entraîne une baisse des performances d'importation.

Le nombre maximal de nœuds de calcul dépend fortement de la taille des données, Idéalement, l'utilisation totale du processeur Spanner doit être comprise entre de 70% à 90%. Cela permet d'obtenir un bon équilibre entre l'efficacité de Spanner et l'exécution d'une tâche sans erreur.

Pour atteindre cet objectif d'utilisation dans la majorité des schémas et des scénarios, nous devons recommandent un nombre maximal de vCPU de nœud de calcul compris entre 4 et 6 fois le nombre de Nœuds Spanner.

Par exemple, pour une instance Spanner à 10 nœuds, avec n1-standard-2 vous devez définir le nombre maximal de nœuds de calcul sur 25, soit 50 vCPU.