Migrer du code avec le traducteur SQL par lot

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

Avant de commencer

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

  1. Assurez-vous de disposer des autorisations requises.
  2. Activez l'API BigQuery Migration.
  3. Collectez les fichiers sources contenant les scripts et les requêtes SQL à traduire.
  4. Facultatif. Créez un fichier de métadonnées pour améliorer la précision de la traduction.
  5. 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.
  6. Choisissez la méthode à utiliser pour envoyer la tâche de traduction.
  7. Importez les fichiers source dans Cloud Storage.

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

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 Google Cloud , 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.

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.

    L'ancien 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.

  • ConsoleGoogle 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.

Créer des fichiers YAML de configuration

Vous pouvez éventuellement créer et utiliser des fichiers de configuration YAML pour personnaliser vos traductions par lots. Ces fichiers peuvent être utilisés pour transformer votre sortie de traduction de différentes manières. Par exemple, vous pouvez créer un fichier YAML de configuration pour modifier la casse d'un objet SQL lors de la traduction.

Si vous souhaitez utiliser la console Google Cloud ou l'API BigQuery Migration pour un job de traduction par lot, vous pouvez importer le fichier YAML de configuration dans le bucket Cloud Storage contenant les fichiers sources.

Si vous souhaitez utiliser le client de traduction par lot, vous pouvez placer le fichier de configuration YAML dans le dossier d'entrée de traduction local.

Importer des fichiers d'entrée dans Cloud Storage

Si vous souhaitez utiliser la Google Cloud 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 pouvez également importer des fichiers de métadonnées ou des fichiers YAML de configuration dans le même bucket Cloud Storage contenant les fichiers sources. 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 et Importer des objets à partir d'un système de fichiers.

Dialectes SQL pris en charge

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 GoogleSQL :

  • Amazon Redshift SQL
  • CLI Apache HiveQL et Beeline
  • IBM Netezza SQL et NZPLSQL
  • Teradata et Teradata Vantage
    • SQL
    • Basic Teradata Query (BTEQ)
    • Teradata Parallel Transport (TPT)

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

  • Apache Spark SQL
  • Azure Snapse T-SQL
  • Greenplum SQL
  • SQL IBM DB2
  • MySQL SQL
  • Oracle SQL, PL/SQL et Exadata
  • PostgreSQL SQL
  • Trino ou PrestoSQL
  • Snowflake SQL
  • SQL Server T-SQL
  • SQLite
  • Vertica SQL

Gérer les fonctions SQL non compatibles avec des fonctions définies par l'utilisateur d'assistance

Lorsque vous traduisez du SQL à partir d'un dialecte source vers BigQuery, il est possible que certaines fonctions n'aient pas d'équivalent direct. Pour y remédier, le service de migration BigQuery (et la communauté BigQuery plus large) fournissent des fonctions définies par l'utilisateur (UDF) d'assistance qui reproduisent le comportement de ces fonctions de dialecte source non compatibles.

Ces fonctions définies par l'utilisateur se trouvent souvent dans l'ensemble de données public bqutil, ce qui permet aux requêtes traduites de les référencer initialement au format bqutil.<dataset>.<function>(). Par exemple, bqutil.fn.cw_count().

Remarques importantes concernant les environnements de production:

Bien que bqutil offre un accès pratique à ces fonctions définies par l'utilisateur d'assistance pour la traduction et les tests initiaux, il est déconseillé de s'appuyer directement sur bqutil pour les charges de travail de production pour plusieurs raisons:

  1. Contrôle des versions: le projet bqutil héberge la dernière version de ces fonctions définies par l'utilisateur, ce qui signifie que leurs définitions peuvent changer au fil du temps. S'appuyer directement sur bqutil peut entraîner un comportement inattendu ou des modifications non valides dans vos requêtes de production si la logique d'une fonction définie par l'utilisateur est mise à jour.
  2. Isolation des dépendances: le déploiement de fonctions définies par l'utilisateur dans votre propre projet isole votre environnement de production des modifications externes.
  3. Personnalisation: vous devrez peut-être modifier ou optimiser ces fonctions définies par l'utilisateur pour mieux les adapter à votre logique métier ou à vos exigences de performances spécifiques. Cela n'est possible que s'ils se trouvent dans votre propre projet.
  4. Sécurité et gouvernance: les règles de sécurité de votre organisation peuvent limiter l'accès direct aux ensembles de données publics tels que bqutil pour le traitement des données de production. La copie de fonctions définies par l'utilisateur dans votre environnement contrôlé est conforme à ces règles.

Déployer des fonctions définies par l'utilisateur d'assistance dans votre projet:

Pour une utilisation fiable et stable en production, vous devez déployer ces fonctions définies par l'utilisateur d'assistance dans votre propre projet et votre propre ensemble de données. Vous pouvez ainsi contrôler entièrement leur version, leur personnalisation et leur accès. Pour obtenir des instructions détaillées sur le déploiement de ces fonctions définies par l'utilisateur, consultez le guide de déploiement des fonctions définies par l'utilisateur sur GitHub. Ce guide fournit les scripts et les étapes nécessaires pour copier les fonctions définies par l'utilisateur dans votre environnement.

Emplacements

La traduction SQL par lot est disponible dans les emplacements de traitement suivants :

Description de la région Nom de la région Détail
Asie-Pacifique
Delhi asia-south2
Hong Kong asia-east2
Jakarta asia-southeast2
Melbourne australia-southeast2
Mumbai asia-south1
Osaka asia-northeast2
Séoul asia-northeast3
Singapour asia-southeast1
Sydney australia-southeast1
Taïwan asia-east1
Tokyo asia-northeast1
Europe
Belgique europe-west1 Icône Feuille Faibles émissions de CO2
Berlin europe-west10 Icône Feuille Faibles émissions de CO2
UE (multirégional) eu
Finlande europe-north1 Icône Feuille Faibles émissions de CO2
Francfort europe-west3 icône feuille Faibles émissions de CO2
Londres europe-west2 icône feuille Faibles émissions de CO2
Madrid europe-southwest1 Icône Feuille Faibles émissions de CO2
Milan europe-west8
Pays-Bas europe-west4 Icône Feuille Faibles émissions de CO2
Paris europe-west9 Icône Feuille Faibles émissions de CO2
Stockholm europe-north2 Icône Feuille Faibles émissions de CO2
Turin europe-west12
Varsovie europe-central2
Zurich europe-west6 Icône Feuille Faibles émissions de CO2
Amériques
Columbus, Ohio us-east5
Dallas us-south1 Icône Feuille Faibles émissions de CO2
Iowa us-central1 Icône Feuille Faibles émissions de CO2
Las Vegas us-west4
Los Angeles us-west2
Mexique northamerica-south1
Virginie du Nord us-east4
Oregon us-west1 Icône Feuille Faibles émissions de CO2
Québec northamerica-northeast1 Icône Feuille Faibles émissions de CO2
São Paulo southamerica-east1 Icône Feuille Faibles émissions de CO2
Salt Lake City us-west3
Santiago southamerica-west1 icône feuille Faibles émissions de CO2
Caroline du Sud us-east1
Toronto northamerica-northeast2 Icône Feuille Faibles émissions de CO2
États-Unis (multirégional) us
Afrique
Johannesburg africa-south1
MiddleEast
Dammam me-central2
Doha me-central1
Israël me-west1

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.

Console

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

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

    Accéder à BigQuery

  2. Dans le menu de navigation, cliquez sur Outils et guide.

  3. Dans le panneau Traduire SQL, cliquez sur Traduire > Traduction par lot.

  4. La page de configuration de la traduction s'ouvre. Saisissez les informations suivantes :

    1. Dans le champ Nom à afficher, saisissez le nom du job 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. Pour Mise en cache des métadonnées, cochez la case Activer la mise en cache des métadonnées pour stocker les informations des fichiers ZIP de métadonnées générés par l'outil dwh-migration-dumper dans le backend BigQuery. Pour les tâches comportant de grands fichiers de métadonnées, ce processus réduit considérablement la latence de traduction pour les requêtes ultérieures. Les métadonnées mises en cache sont actives pendant 7 jours maximum. Cette fonctionnalité est disponible en preview. Pour demander de l'aide ou envoyer des commentaires concernant cette fonctionnalité, contactez bq-edw-migration-support@google.com.

    3. 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 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.

    4. 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 consoleGoogle Cloud .

      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 Google Cloud :

      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 Google Cloud .
    5. Facultatif. Pour générer des suggestions d'IA de traduction à l'aide du modèle Gemini, cochez la case Suggestions d'IA Gemini. Les suggestions sont basées sur le fichier YAML de configuration se terminant par .ai_config.yaml et situé dans le répertoire Cloud Storage. Chaque type de sortie de suggestion est enregistré dans son propre sous-répertoire du dossier de sortie avec le format de dénomination REWRITETARGETSUGGESTION_TYPE_suggestion. Par exemple, les suggestions de personnalisation SQL cible améliorée par Gemini sont stockées dans target_sql_query_customization_suggestion, et l'explication de la traduction générée par Gemini est stockée dans translation_explanation_suggestion. Pour savoir comment écrire le fichier YAML de configuration pour les suggestions d'IA, consultez Créer un fichier YAML de configuration basé sur Gemini.

  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.

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 de la page d'accueil de la consoleGoogle Cloud du projet.
    • gcs_bucket: saisissez le nom du bucket Cloud Storage que le client de traduction par lot utilise 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 Google Cloud .

  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.

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 Google Cloud . Si vous avez utilisé la console Google Cloud 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.
  • Fichiers de suggestions d'IA.

Sortie de la consoleGoogle Cloud

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

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

    Accéder à BigQuery

  2. Dans le menu de navigation, cliquez sur Traduction SQL.

  3. Dans la liste des jobs de traduction, recherchez le job dont vous souhaitez afficher les détails. Cliquez ensuite sur le nom du job de traduction. Vous pouvez voir une visualisation Sankey qui illustre la qualité globale de la tâche, le nombre de lignes de code d'entrée (à l'exception des lignes vides et des commentaires) et une liste des problèmes survenus lors du processus de traduction. Vous devez hiérarchiser les corrections de gauche à droite. Les problèmes à un stade précoce peuvent entraîner d'autres problèmes aux étapes suivantes.

  4. Pointez sur les barres d'erreur ou d'avertissement, puis examinez les suggestions pour déterminer les prochaines étapes de débogage de la tâche de traduction.

  5. Sélectionnez l'onglet Résumé du journal pour afficher un résumé des problèmes de traduction, y compris les catégories de problèmes, les actions suggérées et la fréquence à laquelle chaque problème s'est produit. Vous pouvez cliquer sur les barres de la visualisation Sankey pour filtrer les problèmes. Vous pouvez également sélectionner une catégorie de problème pour afficher les messages de journal associés.

  6. Sélectionnez l'onglet Messages de journal pour afficher plus de détails sur chaque problème de traduction, y compris 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. Vous pouvez cliquer sur les barres de la visualisation Sankey pour filtrer les problèmes. Vous pouvez sélectionner un problème dans l'onglet Messages de journal pour ouvrir l'onglet Code dans lequel les fichiers d'entrée et de sortie sont affichés, le cas échéant.

  7. Cliquez sur l'onglet Informations sur la tâche 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 Google Cloud , procédez comme suit:

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

    Accéder à BigQuery

  2. Dans le menu 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 ou sur Autres options > Afficher les détails.

  4. Dans l'onglet Informations sur la tâche, dans la section Rapport de traduction, cliquez sur 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
Horodatage 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.
Environnement 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).
Catégorie Catégorie du problème de traduction.
SourceType Source de ce problème. La valeur de cette colonne peut être SQL (ce qui indique un problème dans les fichiers SQL d'entrée) ou METADATA (ce qui indique un problème dans le package de métadonnées).
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.

Onglet Code

L'onglet "Code" vous permet de consulter des informations supplémentaires sur les fichiers d'entrée et de sortie d'un job de traduction donné. Dans l'onglet "Code", vous pouvez examiner les fichiers utilisés dans un job de traduction, comparer un fichier d'entrée et sa traduction à la recherche d'inexactitudes, et afficher les résumés et les messages de journal d'un fichier spécifique dans un job.

Pour accéder à l'onglet "Code", procédez comme suit :

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

    Accéder à BigQuery

  2. Dans le menu 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 ou sur Autres options > Afficher les détails.

  4. Sélectionnez l'onglet Code. L'onglet "Code" comprend les panneaux suivants:

    Affichez l&#39;onglet &quot;Code&quot; sur la page de traduction SQL.

    • Explorateur de fichiers: contient tous les fichiers SQL utilisés pour la traduction. Cliquez sur un fichier pour afficher son entrée et sa sortie de traduction, ainsi que les problèmes de traduction associés.
    • Entrée améliorée par Gemini: code SQL d'entrée traduit par le moteur de traduction. Si vous avez spécifié des règles de personnalisation Gemini pour le code SQL source dans la configuration Gemini, le traducteur transforme d'abord l'entrée d'origine, puis traduit l'entrée améliorée par Gemini. Pour afficher l'entrée d'origine, cliquez sur Afficher l'entrée d'origine.
    • Sortie de traduction: résultat de la traduction. Si vous avez spécifié des règles de personnalisation Gemini pour le code SQL cible dans la configuration Gemini, la transformation est appliquée au résultat traduit en tant que sortie améliorée par Gemini. Si une sortie optimisée par Gemini est disponible, vous pouvez cliquer sur le bouton Suggestion Gemini pour examiner la sortie optimisée par Gemini.
  5. Facultatif: Pour afficher un fichier d'entrée et son fichier de sortie dans le traducteur SQL interactif de BigQuery, cliquez sur Modifier. Vous pouvez modifier les fichiers et enregistrer le fichier de sortie dans Cloud Storage.

Onglet "Configuration"

Vous pouvez ajouter, renommer, afficher ou modifier vos fichiers YAML de configuration dans l'onglet Configuration.L'explorateur de schémas affiche la documentation des types de configuration compatibles pour vous aider à écrire vos fichiers YAML de configuration. Après avoir modifié les fichiers YAML de configuration, vous pouvez relancer la tâche pour utiliser la nouvelle configuration.

Pour accéder à l'onglet "Configuration", procédez comme suit:

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

    Accéder à BigQuery

  2. Dans le menu 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 ou sur Autres options > Afficher les détails.

  4. Dans la fenêtre Détails de la traduction, cliquez sur l'onglet Configuration.

Affichez l&#39;onglet &quot;Configuration&quot; de la page de traduction SQL.

Pour ajouter un fichier de configuration:

  1. Cliquez sur more_vert Autres options > Créer un fichier YAML de configuration.
  2. Un panneau s'affiche, dans lequel vous pouvez choisir le type, l'emplacement et le nom du nouveau fichier YAML de configuration.
  3. Cliquez sur Créer.

Pour modifier un fichier de configuration existant:

  1. Cliquez sur le fichier YAML de configuration.
  2. Modifiez le fichier, puis cliquez sur Enregistrer.
  3. Cliquez sur Exécuter à nouveau pour exécuter une nouvelle tâche de traduction qui utilise les fichiers YAML de configuration modifiés.

Pour renommer un fichier de configuration existant, cliquez sur more_vert Autres options > Renommer.

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.

Déboguer des requêtes SQL traduites par lot avec le traducteur SQL interactif

Vous pouvez utiliser le traducteur SQL interactif de BigQuery pour examiner ou déboguer une requête SQL en utilisant les mêmes métadonnées ou informations de mappage d'objets que votre base de données source. Une fois que vous avez terminé une tâche de traduction par lot, BigQuery génère un ID de configuration de traduction contenant des informations sur les métadonnées de la tâche, le mappage d'objets ou le chemin de recherche de schéma, selon le cas de la requête. Vous utilisez l'ID de configuration de traduction par lot avec le traducteur SQL interactif pour exécuter des requêtes SQL avec la configuration spécifiée.

Pour démarrer une traduction SQL interactive à l'aide d'un ID de configuration de traduction par lot, procédez comme suit :

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

    Accéder à BigQuery

  2. Dans le menu de navigation, cliquez sur Traduction SQL.

  3. Dans la liste des jobs de traduction, recherchez celui qui vous intéresse, puis cliquez sur Autres options > Ouvrir la traduction interactive.

    La traduction SQL interactive BigQuery s'ouvre désormais avec l'ID de configuration de traduction par lot correspondant. Pour afficher l'ID de configuration de traduction de la traduction interactive, cliquez sur Plus > Paramètres de traduction dans le traducteur SQL interactif.

Pour déboguer un fichier de traduction par lot dans le traducteur SQL interactif, procédez comme suit:

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

    Accéder à BigQuery

  2. Dans le menu de navigation, cliquez sur Traduction SQL.

  3. Dans la liste des jobs de traduction, recherchez celui qui vous intéresse, puis cliquez sur son nom ou sur Autres options > Afficher les détails.

  4. Dans la fenêtre Détails de la traduction, cliquez sur l'onglet Code.

  5. Dans l'explorateur de fichiers, cliquez sur le nom de votre fichier pour l'ouvrir.

  6. À côté du nom de fichier de sortie, cliquez sur Modifier pour ouvrir les fichiers dans le traducteur SQL interactif (Aperçu).

    Les fichiers d'entrée et de sortie sont renseignés dans le traducteur SQL interactif, qui utilise désormais l'ID de configuration de traduction par lot correspondant.

  7. Pour enregistrer le fichier de sortie modifié dans Cloud Storage, dans le traducteur SQL interactif, cliquez sur Enregistrer > Enregistrer dans GCS.

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.

Résoudre les erreurs de traduction

Problèmes de traduction RelationNotFound ou AttributeNotFound

La traduction fonctionne mieux avec des LDD de métadonnées. Lorsque les définitions d'objets SQL sont introuvables, le moteur de traduction génère des erreurs RelationNotFound ou AttributeNotFound. Nous vous recommandons d'utiliser l'extracteur de métadonnées pour générer des packages de métadonnées afin de vous assurer que toutes les définitions d'objets sont présentes. L'ajout de métadonnées est la première étape recommandée pour résoudre la plupart des erreurs de traduction, car cela permet souvent de corriger de nombreuses autres erreurs causées indirectement par un manque de métadonnées.

Pour en savoir plus, consultez la page Générer des métadonnées pour la traduction et l'évaluation.

Tarifs

L'utilisation du traducteur SQL par lot est gratuite. En revanche, le stockage des fichiers d'entrée et de sortie entraîne des frais normaux. Pour en savoir plus, consultez les tarifs de stockage.

Étapes suivantes

Découvrez les étapes suivantes de la migration d'entrepôts de données :