Importer des données à partir de bases de données autres que Spanner

Cette page explique comment préparer les fichiers Avro que vous avez exportés à partir de bases de données autres que Spanner, puis les importer dans Spanner. Si vous souhaitez importer une base de données Spanner que vous avez précédemment exportée, consultez la page Importer des fichiers Avro Spanner.

Le processus utilise Dataflow. Il importe les données d'un bucket Cloud Storage contenant un ensemble de fichiers Avro et un fichier manifeste JSON spécifiant les tables de destination et les fichiers Avro qui renseignent chaque table.

Avant de commencer

Pour importer 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 conditions de quota requises pour les jobs d'importation:

• 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 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. Il n'est pas nécessaire de spécifier une taille pour ce bucket.
• Dataflow : les tâches d'importation 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, vous devez définir les quotas initiaux Compute Engine utilisés par Dataflow. Ces quotas représentent les quantités maximales de ressources que Dataflow pourra 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 pas d'autres réglages à effectuer. Dataflow assure un autoscaling qui vous permet de ne payer que pour les ressources réellement utilisées lors de l'importation. 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 dont vous avez besoin pour exporter une base de données, demandez à votre administrateur de vous accorder le les rôles IAM suivants sur le compte de service de nœud de calcul 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 d'une base de données autre que Spanner vers des fichiers Avro

Le processus d'importation apporte des données issues de fichiers Avro situés dans un bucket Cloud Storage. Vous pouvez exporter des données au format Avro depuis n'importe quelle source et utiliser toutes les méthodes disponibles pour le faire.

Pour exporter des données d'une base de données autre que Spanner vers des fichiers Avro, procédez comme suit :

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

• Vous pouvez exporter les données à l'aide de n'importe lequel des types primitifs Avro, ainsi qu'avec le type complexe Tableau.

• Chaque colonne de vos fichiers Avro doit utiliser l'un des types de colonne suivants :

  • ARRAY
  • BOOL
  • BYTES^*
  • DOUBLE
  • FLOAT
  • INT
  • LONG^†
  • STRING^‡

  ^* Une colonne de type BYTES permet d'importer un type NUMERIC Spanner. Pour en savoir plus, consultez la section Mappages recommandés suivante.

  ^†,‡ Vous pouvez importer un type LONG stockant un horodatage ou un type STRING stockant un horodatage en tant que type TIMESTAMP Spanner. Pour en savoir plus, consultez la section Mappages recommandés ci-dessous.

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

• 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 les importer dans un bucket Cloud Storage. Pour obtenir des instructions détaillées, consultez Importer des objets dans votre Cloud Storage.

Importer des fichiers Avro depuis des bases de données autres que Spanner vers Spanner

Pour importer des fichiers Avro d'une base de données autre que Spanner vers Spanner, procédez comme suit :

1. Créez des tables cibles et définissez le schéma de votre base de données Spanner.
2. Créez un fichier spanner-export.json dans votre bucket Cloud Storage.
3. Exécutez une tâche d'importation Dataflow à l'aide de la CLI gcloud.

Étape 1: Créez le schéma de votre base de données Spanner

Avant d'exécuter votre importation, vous devez créer la table cible dans Spanner et en définir le schéma.

Vous devez créer un schéma qui utilise le type de colonne approprié pour chaque colonne des fichiers Avro.

Mappages recommandés

GoogleSQL

Type de colonne Avro	Type de colonne Spanner
ARRAY	ARRAY
BOOL	BOOL
BYTES	BYTES NUMERIC (lorsque le type de colonne est défini sur BYTES avec les paramètres suivants : logicalType=decimal, precision=38 et scale=9. Si ces spécifications exactes sont omises, le champ est traité comme une valeur BYTES Spanner. Pour en savoir plus, consultez la documentation sur le type logique décimal Avro.)
DOUBLE	FLOAT64
FLOAT	FLOAT64
INT	INT64
LONG	INT64 TIMESTAMP lorsque LONG représente le nombre de microsecondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC (1970-01-01 00:00:00 UTC)
STRING	STRING TIMESTAMP lorsque STRING représente un horodatage au format canonique pour les requêtes SQL.

PostgreSQL

Type de colonne Avro	Type de colonne Spanner
ARRAY	ARRAY
BOOL	BOOLEAN
BYTES	BYTEA NUMERIC (lorsque le type de colonne est défini sur BYTEA avec les paramètres suivants : logicalType=decimal, precision=147455 et scale=16383. Si vous n'indiquez pas ces spécifications exactes, le champ est traité comme une valeur BYTEA. Pour en savoir plus, consultez la documentation sur le type logique décimal Avro.)
DOUBLE	DOUBLE PRECISION
FLOAT	DOUBLE PRECISION
INT	BIGINT
LONG	BIGINT TIMESTAMP lorsque LONG représente le nombre de microsecondes écoulées depuis le 1er janvier 1970 à 00:00:00 UTC (1970-01-01 00:00:00 UTC)
STRING	CHARACTER VARYING TIMESTAMP lorsque STRING représente un code temporel au format canonique pour les requêtes SQL, par exemple '2022-05-28T07:08:21.123456789Z' ou '2021-12-19T16:39:57-08:00'.

Remarque :Si une colonne de vos données Avro contient des valeurs NULL, vous devez vous assurer que vous pouvez faire en sorte que la colonne correspondante de votre table Spanner puisse avoir une valeur nulle.

Étape 2 : Créez un fichier spanner-export.json

Vous devez également créer un fichier nommé spanner-export.json dans votre bucket Cloud Storage. Ce fichier spécifie le dialecte de la base de données et contient un tableau tables qui répertorie le nom et les emplacements des fichiers de données pour chaque table.

Le contenu du fichier a le format suivant :

{
  "tables": [
   {
    "name": "TABLE1",
    "dataFiles": [
      "RELATIVE/PATH/TO/TABLE1_FILE1",
      "RELATIVE/PATH/TO/TABLE1_FILE2"
    ]
   },
   {
    "name": "TABLE2",
    "dataFiles": ["RELATIVE/PATH/TO/TABLE2_FILE1"]
   }
  ],
  "dialect":"DATABASE_DIALECT"
}

Où DATABASE_DIALECT = {GOOGLE_STANDARD_SQL | POSTGRESQL}

Si l'élément de dialecte est omis, la valeur par défaut du dialecte est GOOGLE_STANDARD_SQL.

Remarque : Les caractères génériques ne sont pas acceptés. Vous devez écrire tous les noms de fichiers en intégralité.

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

Pour démarrer votre tâche d'importation, suivez les instructions permettant d'utiliser la Google Cloud CLI et d'exécuter une tâche avec le modèle Avro vers Spanner.

Une fois que vous avez démarré une tâche d'importation, vous pouvez afficher les détails de cette tâche dans la console Google Cloud.

Une fois la tâche d'importation terminée, ajoutez les éventuels index secondaires et clés étrangères.

Remarque :Pour éviter des frais de transfert de données sortants, choisissez une région qui chevauche l'emplacement de votre bucket Cloud Storage. Pour en savoir plus, consultez la section Choisir une région ci-dessous.

Remarque : Le job Dataflow ne résout pas les tables entrelacées ni les contraintes de clé étrangère. Vous risquez donc de rencontrer des erreurs d'écriture en raison de violations de l'intégrité référentielle. Supprimez toutes les relations entrelacées ou clés étrangères avant de lancer la tâche Dataflow.

Choisissez une région pour votre job d'importation

Vous pouvez être amené à choisir une région différente selon l'emplacement de votre bucket Cloud Storage. Pour éviter les frais de transfert de données sortants, choisissez une région correspondant à 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. Consultez les tarifs de transfert de données Cloud Storage pour choisir la région qui génère 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, vous pouvez consulter les détails de cette tâche et les journaux associés dans la section Dataflow de la console Google Cloud.

Afficher les détails d'un job 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 la tâche Dataflow.

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

1. Accédez à la page des jobs 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 tâche.

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 aux détails de cette 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 affiché à côté de Logs (Journaux).

   La console Google Cloud affiche les journaux du job. 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 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.

Consultez le Latence d'écriture de 99% dans le l'onglet Surveillance de votre base de données Spanner dans console Google Cloud. Si elle affiche des valeurs élevées (plusieurs secondes), cela signifie que l'instance est surchargée, ce qui entraîne l'expiration et l'échec de l'écriture.

L'une des causes de latence élevée est que le job Dataflow est en cours d'exécution utilisent trop de nœuds de calcul, ce qui entraîne une charge trop importante sur Spanner Compute Engine.

Pour spécifier une limite de nœuds de calcul Dataflow, au lieu d'utiliser l'onglet "Import/Export" (Importer/Exporter) sur la page d'informations sur l'instance de votre base de données Spanner dans la console Google Cloud, vous devez démarrer l'importation à l'aide du modèle Cloud Storage Avro vers Spanner Dataflow et spécifier le nombre maximal de nœuds de calcul, comme décrit ci-dessous :

Console

Si vous utilisez la console Dataflow, le paramètre Nombre maximal de nœuds de calcul se trouve dans la section Paramètres facultatifs de la page Créer une tâche à partir d'un modèle.

Accéder à Dataflow

gcloud

Exécutez la commande 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_Avro_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 données Spanner bases de données:

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 part du principe que vous avez l'intention d'utiliser un réseau VPC en mode automatique nommé default dans le même projet que le 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 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.

• Veillez à ce que les ressources Dataflow soient suffisantes : si les ressources de votre tâche Dataflow sont limitées par certains quotas Compute Engine correspondants, la page Dataflow associée à cette tâche dans la console Google Cloud affiche une icône d'avertissement  ainsi qu'un message de journalisation :

  

  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 qu'une instance présente un taux d'utilisation du processeur supérieur à 65 %, vous pouvez augmenter la capacité de calcul pour 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

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

• Taille de la base de données Spanner : le temps de traitement et les ressources requises augmentent avec la quantité de données à traiter.

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

  • Nombre de tables
  • Taille des lignes
  • 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, ce qui entraîne des erreurs lorsque le volume de données est particulièrement important.

• Charge existante sur Spanner : une tâche d'importation ajoute une charge de processeur importante 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 associée à Spanner doit être comprise entre 70 % et 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 utilisant des nœuds de calcul n1-standard-2, vous devez définir un nombre maximal de nœuds de calcul sur 25, ce qui donne 50 processeurs virtuels.