Migrer du code avec le traducteur SQL par lot

Ce document explique comment utiliser le traducteur SQL par lots dans BigQuery pour traduire des scripts écrits dans d'autres dialectes SQL en requêtes SQL standard BigQuery. Ce document est destiné aux utilisateurs qui connaissent déjà la console Google Cloud.

La traduction SQL par lot fait partie du service de migration BigQuery. Le traducteur SQL par lot peut traduire les dialectes SQL suivants en langage SQL standard BigQuery :

  • Amazon Redshift SQL
  • Teradata SQL, à l'exception de SPL

De plus, la traduction des dialectes SQL suivants est disponible en version bêta :

  • Apache HiveQL
  • Apache Spark SQL
  • Azure Snapse T-SQL
  • Basic Teradata Query (BTEQ)
  • IBM Netezza SQL/NZPLSQL
  • Oracle SQL, PL/SQL et Exadata
  • Presto SQL
  • Snowflake SQL
  • SQL Server T-SQL
  • Teradata SPL
  • Vertica SQL

Autorisations requises

Vous devez disposer des autorisations suivantes sur le projet pour activer le service de migration BigQuery :

  • resourcemanager.projects.get
  • serviceusage.services.enable
  • serviceusage.services.get

Vous devez disposer des autorisations suivantes sur le projet pour accéder au service de migration BigQuery et l'utiliser :

  • bigquerymigration.workflows.create
  • bigquerymigration.workflows.get
  • bigquerymigration.workflows.list
  • bigquerymigration.workflows.delete
  • bigquerymigration.subtasks.get
  • bigquerymigration.subtasks.list

    Vous pouvez également utiliser les rôles suivants pour obtenir les mêmes autorisations :

    • bigquerymigration.viewer - Accès en lecture seule
    • bigquerymigration.editor - Accès en lecture/écriture

Pour accéder aux buckets Cloud Storage pour les fichiers d'entrée et de sortie, procédez comme suit :

  • storage.objects.get sur le bucket Cloud Storage source
  • storage.objects.list sur le bucket Cloud Storage source
  • storage.objects.create sur le bucket Cloud Storage de destination

Vous pouvez disposer de toutes les autorisations Cloud Storage nécessaires ci-dessus à partir des rôles suivants :

  • roles/storage.objectAdmin
  • roles/storage.admin

Avant de commencer

Avant d'envoyer une tâche de traduction, procédez comme suit :

  1. Activez l'API BigQuery Migration.
  2. Collectez les fichiers sources contenant les scripts et les requêtes SQL à traduire.
  3. Facultatif. Créez un fichier de métadonnées pour améliorer la précision de la traduction.
  4. Facultatif. Déterminez si vous devez mapper les noms d'objets SQL dans les fichiers sources aux nouveaux noms dans BigQuery. Déterminez les règles de mappage de noms à utiliser si nécessaire.
  5. Choisissez la méthode à utiliser pour envoyer la tâche de traduction.
  6. Importez les fichiers source dans Cloud Storage.

Activer l'API BigQuery Migration

Si votre projet Google Cloud CLI a été créé avant le 15 février 2022, activez l'API BigQuery Migration comme suit :

  1. Dans la console, accédez à la page API BigQuery Migration.

    Accéder à l'API BigQuery Migration

  2. Cliquez sur Activer.

Collecter les fichiers sources

Les fichiers source doivent être des fichiers texte contenant un langage SQL valide pour le dialecte source. Les fichiers sources peuvent également inclure des commentaires. Faites de votre mieux pour vous assurer que le langage SQL est valide, en utilisant les méthodes à votre disposition.

Créer des fichiers de métadonnées

Pour aider le service à générer des résultats de traduction plus précis, nous vous recommandons de fournir des fichiers de métadonnées. Toutefois, ce n'est pas obligatoire.

Vous pouvez utiliser l'outil de ligne de commande dwh-migration-dumper pour générer les informations de métadonnées ou fournir vos propres fichiers de métadonnées. Une fois les fichiers de métadonnées préparés, vous pouvez les inclure avec les fichiers sources dans le dossier source de la traduction. Le traducteur les détecte automatiquement et les utilise pour traduire les fichiers sources, vous n'avez pas besoin de configurer de paramètres supplémentaires pour l'activer.

Pour générer des informations de métadonnées à l'aide de l'outil dwh-migration-dumper, consultez la page Générer des métadonnées pour la traduction.

Pour fournir vos propres métadonnées, collectez les instructions LDD (langage de définition de données) des objets SQL de votre système source dans des fichiers texte distincts.

Mapper les noms d'objet SQL

Vous pouvez éventuellement effectuer un mappage des noms de sortie lors de la traduction par lot. Lorsque vous utilisez le mappage des noms de sortie, vous spécifiez des règles de mappage de noms qui modifient les noms des objets SQL du système source en nouveaux noms dans BigQuery. Par exemple, vous pouvez avoir l'objet schema1.table1 dans votre système source et vous souhaitez que cet objet soit nommé project1.dataset1.table1 dans BigQuery. Si vous utilisez le mappage des noms de sortie, vous devez définir vos règles de mappage de noms avant de démarrer une tâche de traduction par lot. Vous pouvez saisir ces règles manuellement lors de la configuration de la tâche ou créer un fichier JSON contenant les règles de mappage des noms et l'importer.

Choisir le mode d'envoi de la tâche de traduction

Vous disposez de trois options pour envoyer une tâche de traduction par lot :

  • Client de traduction par lot : configurez une tâche en modifiant les paramètres dans un fichier de configuration et en envoyant la tâche à l'aide de la ligne de commande. Cette approche ne nécessite pas l'importation de fichiers sources dans Cloud Storage. Le client utilise toujours Cloud Storage pour stocker les fichiers lors du traitement des tâches de traduction.

    Le client de traduction par lot est un client Python Open Source qui vous permet de traduire les fichiers sources situés sur votre ordinateur local, puis d'obtenir les fichiers traduits en sortie dans un répertoire local. Configurez le client pour une utilisation de base en modifiant quelques paramètres dans son fichier de configuration. Si vous le souhaitez, vous pouvez également configurer le client pour traiter des tâches plus complexes telles que le remplacement de macros, et le pré et post-traitement des entrées et des sorties de traduction. Pour en savoir plus, consultez le fichier readme du client de traduction par lot.

  • Console Google Cloud : configurez et envoyez une tâche à l'aide d'une interface utilisateur. Cette approche nécessite l'importation de fichiers sources dans Cloud Storage.

  • API BigQuery Migration : configurez et envoyez une tâche de manière automatisée. Cette approche nécessite l'importation de fichiers sources dans Cloud Storage.

Importer des fichiers d'entrée dans Cloud Storage

Si vous souhaitez utiliser la console ou l'API BigQuery Migration pour effectuer une tâche de traduction, vous devez importer les fichiers sources contenant les requêtes et les scripts à traduire dans Cloud Storage. Vous devez également importer les fichiers de métadonnées que vous avez créés. Pour en savoir plus sur la création de buckets et l'importation de fichiers dans Cloud Storage, consultez les pages Créer des buckets de stockage et Importer des objets.

Envoyer une tâche de traduction

Procédez comme suit pour démarrer une tâche de traduction, afficher sa progression et consulter les résultats.

Client de traduction par lot

  1. Installez le client de traduction par lot et Google Cloud CLI.

  2. Générez un fichier d'identifiants gcloud CLI.

  3. Dans le répertoire d'installation du client de traduction par lot, utilisez l'éditeur de texte de votre choix pour ouvrir le fichier config.yaml et modifier les paramètres suivants :

    • project_number : saisissez le numéro du projet que vous souhaitez utiliser pour la tâche de traduction par lot. Vous le trouverez dans le volet Informations sur le projet du tableau de bord de la console du projet.
    • gcs_bucket : saisissez le nom du bucket Cloud Storage que le client de traduction par lot doit utiliser pour stocker les fichiers lors du traitement de la tâche de traduction.
    • input_directory : saisissez le chemin absolu ou relatif au répertoire contenant les fichiers sources et les fichiers de métadonnées.
    • output_directory : saisissez le chemin absolu ou relatif au répertoire cible pour les fichiers traduits.
  4. Enregistrez les modifications et fermez le fichier config.yaml.

  5. Placez vos fichiers source et de métadonnées dans le répertoire d'entrée.

  6. Exécutez le client de traduction par lot à l'aide de la commande suivante :

    bin/dwh-migration-client
    

    Une fois la tâche de traduction créée, vous pouvez consulter son état dans la liste des tâches de traduction de la console.

  7. Facultatif. Une fois la tâche de traduction terminée, supprimez les fichiers créés par la tâche dans le bucket Cloud Storage afin d'éviter des frais de stockage.

Console

Cette procédure suppose que vous avez déjà importé des fichiers sources dans un bucket Cloud Storage.

  1. Dans la console, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans la section Migration du panneau de navigation, cliquez sur Traduction SQL.

  3. Cliquez sur Démarrer la traduction.

  4. Remplissez la boîte de dialogue de configuration de la traduction.

    1. Dans le champ Nom à afficher, saisissez le nom de la tâche de traduction. Le nom peut contenir des lettres, des chiffres ou des traits de soulignement.
    2. Dans le champ Emplacement de traitement, sélectionnez l'emplacement où vous souhaitez exécuter la tâche de traduction. Par exemple, si vous êtes en Europe et que vous ne souhaitez pas que vos données dépassent les limites de l'emplacement, sélectionnez la région eu. La tâche de traduction est plus performante lorsque vous choisissez le même emplacement que le bucket de fichiers source.
    3. Pour le champ Dialecte source, sélectionnez le dialecte SQL que vous souhaitez traduire.
    4. Pour le champ Dialecte cible, sélectionnez BigQuery.
  5. Cliquez sur Suivant.

  6. Pour Emplacement source, spécifiez le chemin d'accès au dossier Cloud Storage contenant les fichiers à traduire. Vous pouvez saisir le chemin d'accès au format bucket_name/folder_name/ ou utiliser l'option Parcourir.

  7. Cliquez sur Suivant.

  8. Pour Emplacement cible, spécifiez le chemin d'accès au dossier Cloud Storage de destination pour les fichiers traduits. Vous pouvez saisir le chemin d'accès au format bucket_name/folder_name/ ou utiliser l'option Parcourir.

  9. Si vous effectuez des traductions qui n'ont pas besoin de noms d'objet par défaut ni de mappage de noms source-cible, passez à l'étape 11. Sinon, cliquez sur Suivant.

  10. Renseignez les paramètres facultatifs dont vous avez besoin.

    1. Facultatif. Dans le champ Base de données par défaut, saisissez un nom de base de données par défaut à utiliser avec les fichiers sources. Le traducteur utilise ce nom de base de données par défaut pour résoudre les noms complets des objets SQL dont le nom de base de données est manquant.

    2. Facultatif. Dans le champ Chemin de recherche de schéma, spécifiez un schéma à rechercher lorsque le traducteur doit résoudre les noms complets des objets SQL dans les fichiers sources où le nom de schéma est manquant. Si les fichiers sources utilisent un certain nombre de noms de schémas différents, cliquez sur Add Schema Name (Ajouter un nom de schéma), puis ajoutez une valeur pour chaque nom de schéma pouvant être référencé.

      Le traducteur effectue une recherche dans les fichiers de métadonnées que vous avez fournis pour valider les tables avec leurs noms de schéma. Si aucune option définitive ne peut être déterminée à partir des métadonnées, le premier nom de schéma que vous saisissez est utilisé par défaut. Pour en savoir plus sur l'utilisation du nom de schéma par défaut, consultez la section Schéma par défaut.

    3. Facultatif. Si vous souhaitez spécifier des règles de mappage de noms pour renommer les objets SQL entre le système source et BigQuery lors de la traduction, vous pouvez fournir un fichier JSON contenant la paire de mappage de noms, ou spécifier les valeurs à mapper à l'aide de la console.

      Pour utiliser un fichier JSON :

      1. Cliquez sur Importer un fichier JSON pour le mappage des noms.
      2. Accédez à l'emplacement d'un fichier de mappage de noms au format approprié, sélectionnez-le, puis cliquez sur Ouvrir.

        Notez que la taille du fichier doit être inférieure à 5 Mo.

      Pour utiliser la console, procédez comme suit:

      1. Cliquez sur Ajouter une paire de mappage de noms.
      2. Ajoutez les parties appropriées du nom de l'objet source dans les champs Base de données, Schéma, Relation et Attribut de la colonne Source.
      3. Ajoutez les parties du nom d'objet cible dans BigQuery dans les champs de la colonne Cible.
      4. Pour Type, sélectionnez un type décrivant l'objet que vous mappez.
      5. Répétez les étapes 1 à 4 jusqu'à ce que vous ayez spécifié toutes les paires de mappage de noms dont vous avez besoin. Notez que vous ne pouvez spécifier que 25 paires de mappages de noms maximum lorsque vous utilisez la console.
  11. Cliquez sur Créer pour démarrer la tâche de traduction.

Une fois la tâche de traduction créée, vous pouvez consulter son état dans la liste des tâches.

API

Cette procédure suppose que vous avez déjà importé des fichiers sources dans un bucket Cloud Storage.

  1. Appelez la méthode create avec un workflow défini.
  2. Appelez ensuite la méthode start pour démarrer le workflow de traduction.

Vous pouvez utiliser les bibliothèques clientes de l'API BigQuery Migration pour Go, Java et Python pour faciliter la configuration et l'envoi de tâches de traduction par lot de manière automatisée.

Explorer le résultat de la traduction

Une fois la tâche de traduction exécutée, vous pouvez afficher des informations sur cette tâche dans la console. Si vous avez utilisé la console ou l'API BigQuery Migration pour exécuter la tâche, vous pouvez afficher les résultats de la tâche dans le bucket Cloud Storage de destination que vous avez spécifié. Si vous avez utilisé le client de traduction par lot pour exécuter la tâche, vous pouvez afficher les résultats de la tâche dans le répertoire de sortie que vous avez spécifié. Le traducteur SQL par lot renvoie les fichiers suivants à la destination spécifiée :

  • Fichiers traduits.
  • Rapport de synthèse sur la traduction au format CSV.
  • Mappage de nom de sortie consommé au format JSON.

Sortie vers la console

Pour afficher les détails d'une tâche de traduction, procédez comme suit :

  1. Dans la console, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans la section Migration du panneau de navigation, cliquez sur Traduction SQL.

  3. Dans la liste des tâches de traduction, recherchez celle qui vous intéresse, puis cliquez sur son nom.

  4. Dans la section Résultats, vous pouvez voir le taux de réussite global de la traduction, le nombre d'instructions traitées et la durée de la tâche.

  5. Cliquez sur l'onglet Actions pour afficher les problèmes de traduction et leur fréquence d'occurrence. Chaque action répertoriée contient des lignes enfants indiquant la catégorie de problème, le message spécifique associé et un lien vers le fichier dans lequel le problème s'est produit.

  6. Sélectionnez l'onglet Configuration de la traduction pour afficher les détails de la configuration de la tâche de traduction.

Rapport récapitulatif

Le rapport récapitulatif est un fichier CSV contenant une table de tous les messages d'avertissement et d'erreur rencontrés lors de la tâche de traduction.

Pour afficher le fichier de résumé dans la console Cloud, procédez comme suit :

  1. Dans la console, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans la section Migration du panneau de navigation, cliquez sur Traduction SQL.

  3. Dans la liste des tâches de traduction, recherchez celle qui vous intéresse, puis cliquez sur Afficher les détails dans la colonne État.

  4. Dans la section Rapport de traduction, cliquez sur batch_translation_report.csv.

  5. Sur la page Détails de l'objet, cliquez sur la valeur de la ligne URL authentifiée pour afficher le fichier dans votre navigateur.

Le tableau suivant décrit les colonnes du fichier de récapitulatif :

Colonne Description
Timestamp Horodatage du problème.
Chemin d'accès du fichier Chemin d'accès au fichier source auquel le problème est associé.
Nom du fichier Le nom du fichier source auquel le problème est associé.
Ligne de script Numéro de la ligne où le problème s'est produit.
Colonne de script Numéro de la colonne où le problème s'est produit.
Composant du transpileur Composant interne du moteur de traduction à l'origine de l'avertissement ou de l'erreur. Cette colonne peut être vide.
Environment Environnement de dialecte de traduction associé à l'avertissement ou à l'erreur. Cette colonne peut être vide.
Nom de l'objet Objet SQL du fichier source associé à l'avertissement ou à l'erreur. Cette colonne peut être vide.
Gravité Niveau de gravité du problème (avertissement ou erreur).
Category Catégorie du problème de traduction.
Message Message d'avertissement ou d'erreur de traduction.
ScriptContext Extrait SQL du fichier source associé au problème.
Action L'action que nous vous recommandons d'effectuer pour résoudre le problème.

Fichier de mappage de noms de sortie utilisé

Ce fichier JSON contient les règles de mappage des noms de sortie utilisées par la tâche de traduction Les règles de ce fichier peuvent différer des règles de mappage des noms de sortie que vous avez spécifiées pour la tâche de traduction, en raison de conflits dans les règles de mappage des noms ou de l'absence de ces règles pour les objets SQL identifiés lors de la traduction. Consultez ce fichier pour déterminer si les règles de mappage des noms doivent être corrigées. Si tel est le cas, créez des règles de mappage des noms de sortie pour résoudre les problèmes que vous identifiez, puis exécutez une nouvelle tâche de traduction.

Fichiers traduits

Un fichier de sortie correspondant à chaque fichier d'entrée est généré dans le chemin de destination. Le fichier de sortie contient la requête traduite.

Limites

Le traducteur ne peut pas traduire les fonctions définies par l'utilisateur depuis des langages autres que SQL, car il ne peut pas les analyser pour déterminer leurs types de données d'entrée et de sortie. Cela entraîne une traduction inexacte des instructions SQL faisant référence à ces fonctions définies par l'utilisateur. Pour vous assurer que les UDF (fonctions définies par l'utilisateur) non-SQL sont correctement référencées lors de la traduction, utilisez un langage SQL valide pour créer des UDF ayant les mêmes signatures.

Par exemple, supposons que vous ayez une UDF écrite en C qui calcule la somme de deux entiers. Pour vous assurer que les instructions SQL faisant référence à cette UDF sont correctement traduites, créez une UDF SQL d'espace réservé qui partage la même signature que l'UDF en C, comme illustré dans l'exemple suivant :

CREATE FUNCTION Test.MySum (a INT, b INT)
  RETURNS INT
  LANGUAGE SQL
  RETURN a + b;

Enregistrez cette UDF dans un fichier texte et incluez ce fichier en tant que fichier source pour la tâche de traduction. Cela permet au traducteur d'apprendre à définir l'UDF et d'identifier les types de données d'entrée et de sortie attendus.

Quota et limites

  • Les quotas de l'API BigQuery Migration s'appliquent.
  • Chaque projet peut comporter au maximum 10 tâches de traduction active.
  • Bien qu'il n'existe aucune limite stricte pour le nombre total de fichiers sources et de métadonnées, nous vous recommandons de limiter ce nombre à 1 000 pour de meilleures performances.

Étape suivante