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. Vous pouvez envoyer et examiner les résultats d'un job de traduction depuis la console Google Cloud ou la ligne de commande.

Remarque : Pour créer une intégration logicielle personnalisée, un pipeline CI/CD automatisé ou un autre workflow programmatique, nous vous recommandons d'appeler directement l'API BigQuery Migration.

Pour obtenir la liste des dialectes SQL compatibles avec ce traducteur SQL, consultez Dialectes SQL compatibles.

Pour obtenir la liste des lieux de traitement acceptés, consultez Emplacements.

Avant de commencer

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

Activer les traductions SQL

Activez l'API requise et obtenez les autorisations nécessaires pour utiliser un traducteur SQL BigQuery. Pour en savoir plus, consultez Activer les traductions SQL.

Autorisations requises

Pour obtenir les autorisations nécessaires pour créer des jobs de traduction avec le traducteur interactif, l'API Translation ou le traducteur SQL par lot, demandez à votre administrateur de vous accorder les rôles IAM suivants sur la ressource parent :

• Afficher et surveiller les jobs de migration : Lecteur d'objets MigrationWorkflow (roles/bigquerymigration.viewer)
• Envoyer des jobs de migration : Éditeur d'objets MigrationWorkflow (roles/bigquerymigration.editor)
• Accédez aux buckets Cloud Storage pour les fichiers d'entrée et de sortie : Administrateur des objets Storage (roles/storage.objectAdmin) : sur les bucket Cloud Storage source et de destination.

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour créer des jobs de traduction avec le traducteur interactif, l'API Translation ou le traducteur SQL par lot. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour créer des jobs de traduction avec le traducteur interactif, l'API Translation ou le traducteur SQL par lot :

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

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

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 d'extraction en ligne de commande dwh-migration-dumper pour générer les informations 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.

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.

Utilisez l'une des options suivantes pour inclure un fichier YAML de configuration dans votre job de traduction.

Console

Importez le fichier de configuration YAML dans le répertoire Cloud Storage qui contient vos fichiers sources. Lorsque vous sélectionnez ce répertoire comme emplacement d'entrée, le fichier YAML de configuration est automatiquement inclus dans le job de traduction.

gcloud

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Les indicateurs que vous utilisez avec la commande gcloud alpha bq translation translate-batch dépendent de l'emplacement du fichier YAML de configuration :

• Si le fichier YAML de configuration se trouve dans le même répertoire que vos fichiers sources, vous n'avez besoin d'aucun indicateur supplémentaire. Lorsque vous définissez ce répertoire dans l'indicateur --source-gcs-uris ou --source-local-dirs, le fichier YAML de configuration est automatiquement inclus dans le job.
• Si le fichier YAML de configuration est stocké séparément sur votre ordinateur local, utilisez l'indicateur --source-local-files pour l'importer et l'ajouter au job.
• Si le fichier YAML de configuration est stocké séparément dans Cloud Storage, utilisez l'indicateur --source-gcs-files pour l'ajouter au job.

Par exemple, la commande suivante importe vos fichiers sources et un fichier YAML de configuration stocké séparément depuis votre ordinateur local, puis exécute le job de traduction :

gcloud alpha bq translation translate-batch \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-local-dirs=LOCAL_DIR=SOURCE_URI \
  --source-local-files=LOCAL_CONFIG_YAML=CONFIG_YAML_URI \
  --target-gcs-path=TARGET_URI

Remplacez les éléments suivants :

• LOCAL_CONFIG_YAML : chemin d'accès local au fichier YAML de configuration, tel que ./configs/change-case.config.yaml.
• CONFIG_YAML_URI : URI Cloud Storage vers lequel la commande importe le fichier YAML de configuration, tel que gs://my_data_bucket/teradata/configs/change-case.config.yaml. Cet URI doit se trouver en dehors du répertoire SOURCE_URI.

Pour obtenir la description des autres espaces réservés, consultez Envoyer une tâche de traduction.

Importer des fichiers d'entrée dans Cloud Storage

Importez les fichiers sources contenant les requêtes et les scripts que vous souhaitez 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 et le même répertoire 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.

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

Deux options s'offrent à vous pour envoyer une tâche de traduction par lot :

• ConsoleGoogle Cloud  : configurez et envoyez un job à l'aide d'une interface utilisateur. Cette approche nécessite l'importation de fichiers sources dans Cloud Storage.

• Google Cloud CLI : envoyez un job depuis la ligne de commande à l'aide de gcloud CLI. La commande translate-batch accepte vos emplacements source et de destination en tant qu'indicateurs, et peut importer des répertoires et des fichiers locaux dans Cloud Storage pour vous. Pour en savoir plus, consultez Envoyer une tâche de traduction.

Les deux options nécessitent que vos fichiers sources soient accessibles dans Cloud Storage et créent le même type de job de traduction. Un job que vous envoyez depuis la ligne de commande apparaît toujours dans la liste des tâches de traduction de la consoleGoogle Cloud .

Envoyer une tâche de traduction

Utilisez l'une des options suivantes pour démarrer une tâche de traduction et afficher sa progression. Pour examiner les résultats par la suite, consultez Explorer le résultat de la traduction.

Console

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

Pour utiliser la console Google Cloud afin d'envoyer un job de traduction par lot, procédez comme suit :

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

   Accéder à la traduction SQL

2. Dans le panneau Traduction SQL, cliquez sur Démarrer la traduction.

3. Dans le champ Configuration de la traduction, saisissez la valeur suivante :

   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 Dialecte cible, sélectionnez GoogleSQL.

4. Cliquez sur Suivant.

5. Pour Détails sur l'emplacement des fichiers, spécifiez les chemins d'accès Cloud Storage à utiliser pour les entrées et les sorties de traduction. Vous pouvez saisir les chemins d'accès au format bucket_name/folder_name/ ou utiliser l'option Parcourir pour accéder à un dossier.

   1. Pour Emplacement du répertoire de sortie, spécifiez le chemin d'accès au dossier Cloud Storage de destination pour les fichiers traduits. Il sert de répertoire racine pour toutes les traductions.
   2. Choisissez un ou plusieurs emplacements de répertoire d'entrée contenant le chemin d'accès aux fichiers SQL à traduire.
   3. Si nécessaire, vous pouvez attribuer à chaque répertoire d'entrée un nom de sous-répertoire de sortie sous le répertoire de sortie racine.

6. Cliquez sur Suivant.

7. Sélectionnez les paramètres facultatifs dont vous avez besoin pour personnaliser les métadonnées et les autres résultats de traduction.

8. Facultatif : Pour personnaliser davantage le comportement de la traduction, créez des fichiers de configuration YAML et placez-les dans le bucket Cloud Storage d'entrée. Ces fichiers peuvent être utilisés pour renommer des objets, activer des optimisations, améliorer les traductions avec Gemini et plus encore. Pour en savoir plus sur les fichiers de configuration YAML, consultez Créer un fichier de configuration YAML.

9. 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 de traduction.

gcloud

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Pour envoyer une tâche de traduction par lot, utilisez la commande gcloud alpha bq translation translate-batch. Les indicateurs que vous utilisez pour identifier vos fichiers sources dépendent de l'emplacement des fichiers (Cloud Storage ou votre machine locale).

Traduire des fichiers SQL dans Cloud Storage

Pour traduire des fichiers SQL que vous avez déjà importés dans Cloud Storage, identifiez les répertoires sources avec l'indicateur --source-gcs-uris. Si vous souhaitez inclure des fichiers qui ne se trouvent pas dans --source-gcs-uris, vous pouvez utiliser le flag --source-gcs-files :

gcloud alpha bq translation translate-batch \
    --source-dialect=SOURCE_DIALECT \
    --target-dialect=TARGET_DIALECT \
    --location=LOCATION \
    --source-gcs-uris=SOURCE_URI \
    --target-gcs-path=TARGET_URI

Remplacez les éléments suivants :

• SOURCE_DIALECT : dialecte des fichiers SQL sources, tel que teradata. Pour connaître les valeurs acceptées, consultez Dialectes SQL acceptés.
• TARGET_DIALECT : dialecte dans lequel traduire les fichiers sources. Exemple :bigquery
• LOCATION : emplacement qui traite le job, par exemple us.
• SOURCE_URI : répertoire Cloud Storage contenant les fichiers sources, tel que gs://my_data_bucket/teradata/input/.
• TARGET_URI : répertoire Cloud Storage qui reçoit les fichiers traduits, tel que gs://my_data_bucket/teradata/output/.

Traduire des fichiers SQL sur votre ordinateur local

Pour traduire des fichiers qui se trouvent sur votre ordinateur local, mappez chaque répertoire local à un URI Cloud Storage avec l'indicateur --source-local-dirs. La commande importe le répertoire dans cet URI, puis inclut l'URI dans la tâche de traduction. Vous n'avez donc pas besoin d'importer les fichiers vous-même :

gcloud alpha bq translation translate-batch \
    --source-dialect=SOURCE_DIALECT \
    --target-dialect=TARGET_DIALECT \
    --location=LOCATION \
    --source-local-dirs=LOCAL_DIR=SOURCE_URI \
    --target-gcs-path=TARGET_URI

Remplacez LOCAL_DIR par le répertoire local contenant les fichiers sources, par exemple ./teradata_queries. Pour obtenir la description des autres espaces réservés, consultez Traduire des fichiers SQL dans Cloud Storage.

Pour mapper des fichiers individuels au lieu de répertoires, utilisez l'option --source-local-files.

Ajouter des indicateurs facultatifs

Pour générer des suggestions Gemini en plus du code SQL traduit, ajoutez l'option --enable-ai-suggestion.

Par défaut, la commande attend la fin du job de traduction. Pour envoyer le job et revenir immédiatement, ajoutez l'indicateur --async. La commande affiche ensuite un ID de traduction que vous pouvez transmettre à la commande gcloud alpha bq translation describe pour vérifier l'état du job :

gcloud alpha bq translation describe TRANSLATION_ID \
    --location=LOCATION

Récupérer les fichiers de sortie

La tâche de traduction écrit ses résultats dans le répertoire Cloud Storage que vous avez défini dans l'indicateur --target-gcs-path. Ce répertoire cible contient les fichiers traduits, le rapport récapitulatif de la traduction et tous les fichiers de suggestions de l'IA.

Pour copier la sortie sur votre ordinateur local, utilisez la commande suivante :

gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY

Remplacez les éléments suivants :

• TARGET_URI : votre URI de base cible, tel que gs://my_data_bucket/teradata/output/.
• LOCAL_DIRECTORY : répertoire local qui reçoit les fichiers.

Votre tâche apparaît également dans la liste des tâches de traduction de la consoleGoogle Cloud , même si vous l'avez envoyée depuis la ligne de commande. Pour examiner la qualité d'un résultat de traduction, consultez Explorer le résultat de la traduction.

Traduire les métadonnées

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

En plus de traduire les scripts SQL, vous pouvez traduire les métadonnées qui décrivent votre entrepôt de données source. Un job de traduction de métadonnées lit les fichiers de métadonnées que vous avez extraits de votre système source et écrit des instructions LDD (langage de définition de données) GoogleSQL qui recréent ces objets dans BigQuery.

L'entrée est constituée d'un ou de plusieurs fichiers ZIP de métadonnées. Pour savoir comment générer ces fichiers avec l'outil dwh-migration-dumper, consultez Générer des métadonnées pour la traduction.

Vous pouvez traduire les métadonnées à l'aide de la console Google Cloud ou de la gcloud CLI. Sélectionnez l'une des options suivantes :

Console

La traduction des métadonnées est une option de sortie pour une tâche de traduction standard :

1. Suivez les étapes décrites dans Envoyer un job de traduction pour configurer un job, en utilisant le répertoire Cloud Storage contenant vos fichiers ZIP de métadonnées comme emplacement d'entrée.
2. Dans Paramètres facultatifs, sélectionnez DDL.
3. Cliquez sur Créer pour créer la tâche.

Le job écrit les instructions LDD traduites dans votre répertoire de sortie, ainsi que tout code SQL traduit.

gcloud

Vous pouvez traduire les métadonnées en tant que job à part entière ou en tant que sortie supplémentaire d'un job de traduction SQL par lot.

Traduire les métadonnées seules

Utilisez la commande gcloud alpha bq translation translate-metadata lorsque vos entrées sont des fichiers ZIP de métadonnées et que vous n'avez pas de code SQL à traduire :

gcloud alpha bq translation translate-metadata \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI

Remplacez les éléments suivants :

• SOURCE_DIALECT : dialecte des métadonnées sources, par exemple teradata. Pour connaître les valeurs acceptées, consultez Dialectes SQL acceptés.
• TARGET_DIALECT : dialecte des tables cibles. Exemple :bigquery
• LOCATION : emplacement qui traite le job, tel que us.
• SOURCE_URI : répertoire Cloud Storage contenant les fichiers ZIP de métadonnées, tel que gs://my_data_bucket/teradata/metadata/.
• TARGET_URI : répertoire Cloud Storage qui reçoit les instructions LDD traduites, par exemple gs://my_data_bucket/teradata/ddl_output/.

Pour pointer vers des fichiers ZIP de métadonnées individuels plutôt que vers un répertoire, utilisez l'indicateur --source-gcs-files. Pour importer des fichiers de métadonnées depuis votre machine locale dans le cadre du job, utilisez l'option --source-local-dirs ou --source-local-files.

Comme pour un job de traduction par lot, la commande attend la fin du job. Ajoutez l'option --async pour envoyer le job et renvoyer immédiatement un ID de traduction.

Traduire des métadonnées dans le cadre d'une traduction SQL par lot

Si vos entrées de traduction par lot incluent déjà vos fichiers ZIP de métadonnées, vous n'avez pas besoin d'un deuxième job. Ajoutez metadata aux résultats de traduction du job par lot avec l'indicateur --target-types. Le job écrit les instructions SQL et LDD traduites en une seule exécution :

gcloud alpha bq translation translate-batch \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI \
  --target-types=sql,metadata

Pour connaître les autres options acceptées par la commande translate-batch, consultez Envoyer une tâche de traduction.

Générer le LDD source

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Lorsque votre code SQL source fait référence à des tables dont vous ne possédez pas les définitions, le traducteur ne peut pas toujours résoudre les objets, ce qui entraîne des problèmes RelationNotFound ou AttributeNotFound.

La meilleure façon de résoudre ces problèmes est de fournir les définitions réelles de vos objets sources. Exécutez l'outil dwh-migration-dumper sur votre système source et incluez le fichier ZIP de métadonnées obtenu dans les entrées de traduction. Pour obtenir des instructions, consultez Générer des métadonnées pour la traduction. Les métadonnées extraites décrivent précisément vos objets. Le traducteur peut donc les résoudre sans avoir à deviner.

Si vous ne parvenez pas à extraire les métadonnées (par exemple, si vous n'avez plus accès au système source), vous pouvez demander à Gemini d'inférer les instructions LDD manquantes à partir de votre code SQL source. Gemini déduit ces instructions LDD de la façon dont les objets sont utilisés dans vos requêtes. Par conséquent, vérifiez toujours ces instructions avant de les utiliser.

Vous pouvez générer le LDD source pour vos traductions à l'aide de la consoleGoogle Cloud ou de la gcloud CLI. Sélectionnez l'une des options suivantes :

Console

Gemini génère des suggestions de LDD source dans le cadre d'un job de traduction régulier :

1. Suivez la procédure décrite dans Envoyer un job de traduction pour configurer un job.
2. Dans Paramètres facultatifs, sélectionnez Suggestions de l'IA Gemini.
3. Cliquez sur Créer pour créer la tâche.

Si la traduction produit des problèmes RelationNotFound ou AttributeNotFound, le job génère des instructions LDD sources suggérées pour les objets non résolus. Le job traduit également votre code SQL, vous n'avez donc pas besoin d'un job distinct.

gcloud

La commande gcloud alpha bq translation generate-source-ddl lit votre code SQL source et renvoie des instructions LDD sources suggérées :

gcloud alpha bq translation generate-source-ddl \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --source-gcs-uris=SOURCE_URI \
  --target-gcs-path=TARGET_URI

Remplacez SOURCE_URI par le répertoire Cloud Storage contenant les fichiers SQL sources et TARGET_URI par le répertoire Cloud Storage qui reçoit les instructions LDD générées. Les autres espaces réservés sont identiques à ceux décrits dans Traduire les métadonnées.

Pour générer des suggestions dans le cadre d'une tâche de traduction, ajoutez l'option --enable-ai-suggestion à la commande translate-batch.

Vous pouvez ensuite fournir les instructions LDD générées en entrée d'un job de traduction ultérieur pour améliorer la qualité de la traduction. Pour en savoir plus, consultez Problèmes de traduction de RelationNotFound ou AttributeNotFound.

Explorer le résultat de la traduction

Vous pouvez consulter les résultats d'un job de traduction dans la console Google Cloud , que le job ait été envoyé depuis la ligne de commande ou la console Google Cloud . 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.
• Fichiers de suggestions de l'IA.

Google Cloud Sortie de la console

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 Traduction SQL.

   Accéder à la traduction SQL

2. 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 du job, le nombre de lignes de code d'entrée (à l'exclusion des lignes vides et des commentaires) et une liste des problèmes survenus lors du processus de traduction. Vous devez résoudre les problèmes de gauche à droite. Les problèmes rencontrés à un stade précoce peuvent en entraîner d'autres aux stades suivants.

3. Pointez sur les barres d'erreur ou d'avertissement, puis examinez les suggestions pour déterminer les prochaines étapes de débogage du job de traduction.

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

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

6. Cliquez sur l'onglet Détails du job pour afficher les détails de la configuration du job de traduction.

Rapport récapitulatif

Le rapport récapitulatif est un fichier CSV contenant un tableau 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 Traduction SQL.

   Accéder à la traduction SQL

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

3. Dans l'onglet Informations sur le job, dans la section Rapport de traduction, cliquez sur translation_report.csv.

4. 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, consulter un comparatif d'un fichier d'entrée et de 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 Traduction SQL.

   Accéder à la traduction SQL

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

3. Sélectionnez l'onglet Code. L'onglet "Code" se compose des panneaux suivants :

   

   • 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 éventuels problèmes de traduction.
   • Entrée optimisée par Gemini : requête SQL d'entrée traduite 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.
   • Résultat de la traduction : résultat de la traduction. Si vous avez spécifié des règles de personnalisation Gemini pour le SQL cible dans la configuration Gemini, la transformation est appliquée au résultat traduit en tant que sortie optimisée par Gemini. Si une sortie optimisée par Gemini est disponible, vous pouvez cliquer sur le bouton Suggestion Gemini pour l'examiner.

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

Remarque : Vous pouvez afficher les résumés et les message de journal du job de traduction sur la page Résultats.

Onglet "Configuration"

Vous pouvez ajouter, renommer, afficher ou modifier vos fichiers YAML de configuration dans l'onglet Configuration. L'explorateur de schéma affiche la documentation des types de configuration compatibles pour vous aider à rédiger vos fichiers YAML de configuration. Après avoir modifié les fichiers YAML de configuration, vous pouvez réexécuter le job 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 Traduction SQL.

   Accéder à la traduction SQL

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

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

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 Réexécuter pour exécuter un nouveau job de traduction qui utilise les fichiers YAML de configuration modifiés.

Vous pouvez renommer un fichier de configuration existant en cliquant sur more_vert Plus d'options > Renommer.

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.

Important : La traduction est effectuée de la manière la plus optimale possible. Dans la mesure du possible, validez les requêtes traduites.

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

Lorsque vous traduisez du code SQL d'un dialecte source vers BigQuery, il est possible que certaines fonctions n'aient pas d'équivalent direct. Pour résoudre ce problème, le service de migration BigQuery (et la communauté BigQuery au sens large) fournit des fonctions définies par l'utilisateur (UDF) d'assistance qui reproduisent le comportement de ces fonctions de dialecte source non compatibles.

Ces UDF 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().

Informations spécifiques aux environnements de production

Bien que bqutil offre un accès pratique à ces UDF d'assistance pour la traduction et les tests initiaux, il n'est pas recommandé de s'appuyer directement sur bqutil pour les charges de travail de production pour les raisons suivantes :

1. Contrôle des versions : le projet bqutil héberge la dernière version de ces UDF, 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 incompatibles dans vos requêtes de production si la logique d'une UDF est mise à jour.
2. Isolation des dépendances : le déploiement d'UDF dans votre propre projet isole votre environnement de production des modifications externes.
3. Personnalisation : vous devrez peut-être modifier ou optimiser ces UDF 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 restreindre l'accès direct aux ensembles de données publics tels que bqutil pour le traitement des données de production. La copie des UDF dans votre environnement contrôlé est conforme à ces règles.

Déployer des UDF d'assistance dans votre projet

Pour vous permettre de contrôler entièrement la version, la personnalisation et l'accès aux UDF, nous vous recommandons de déployer des UDF d'assistance dans votre propre projet et ensemble de données pour une utilisation en production fiable et stable. Pour en savoir plus sur les scripts et les étapes nécessaires au déploiement des UDF d'assistance dans votre environnement, consultez Déployer les UDF.

Dépannage

Cette section explique comment déboguer des requêtes individuelles et résoudre les erreurs de traduction les plus courantes.

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.

Vous pouvez déboguer les requêtes SQL traduites par lot à l'aide de la consoleGoogle Cloud ou de la gcloud CLI. Sélectionnez l'une des options suivantes :

Console

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 Traduction SQL.

   Accéder à la traduction SQL

2. 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 Outils > Traduction de requêtes > 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 Traduction SQL.

   Accéder à la traduction SQL

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

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

4. Dans l'explorateur de fichiers, cliquez sur le nom du fichier pour l'ouvrir.

5. À côté du nom du 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.

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

gcloud

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Pour retraduire et inspecter une seule requête sans ouvrir la consoleGoogle Cloud , utilisez la commande gcloud alpha bq translation translate. Cela est utile lorsque vous avez réduit un problème de traduction par lot à une seule requête et que vous souhaitez l'itérer localement.

gcloud alpha bq translation translate \
  --source-dialect=SOURCE_DIALECT \
  --target-dialect=TARGET_DIALECT \
  --location=LOCATION \
  --input-file=INPUT_FILE \
  --output-file=OUTPUT_FILE \
  --translation-log-file=LOG_FILE \
  --explanation-output-file=EXPLANATION_FILE

Remplacez les éléments suivants :

• INPUT_FILE : fichier local contenant la requête à traduire. Si vous omettez ce flag, la commande lit la requête à partir de l'entrée standard.
• OUTPUT_FILE : fichier local qui reçoit la requête traduite. Si vous omettez cet indicateur, la commande écrit la requête dans la sortie standard.
• LOG_FILE : fichier YAML local qui reçoit les journaux de traduction, lesquels contiennent les mêmes messages d'erreur que ceux affichés dans l'onglet Messages du journal de la consoleGoogle Cloud .
• EXPLANATION_FILE : fichier local qui reçoit une explication de la traduction générée par Gemini.

Pour réutiliser les métadonnées de votre job par lot afin que la requête résolve les mêmes objets, ajoutez l'indicateur --metadata-gcs-uri. Pour en savoir plus, consultez Traduire une requête en langage GoogleSQL.

Résoudre les erreurs de traduction

Les sections suivantes décrivent les erreurs courantes rencontrées lors de l'utilisation du traducteur SQL par lot.

Problèmes de traduction RelationNotFound ou AttributeNotFound

Après avoir traduit une requête à l'aide du traducteur SQL par lot, il est possible que la traduction échoue et que l'erreur RelationNotFound ou AttributeNotFound s'affiche.

Pour trouver les traductions ayant échoué, accédez à la page Détails de la traduction dans BigQuery de la console Google Cloud , puis ouvrez l'onglet Messages du journal.

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 Générer des métadonnées pour la traduction et l'évaluation.

Résoudre les problèmes de traduction avec Gemini

Aperçu

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Remarque : Pour demander des commentaires ou de l'aide concernant cette fonctionnalité, contactez [e-mail].

Pour corriger les tâches de traduction ayant échoué avec les erreurs RelationNotFound ou AttributeNotFound, vous pouvez également utiliser Gemini pour résoudre ces problèmes :

1. Accédez à la page Détails de la traduction et ouvrez l'onglet Messages du journal.
2. Cliquez sur la requête qui comporte le message RelationNotFound ou AttributeNotFound dans la colonne Catégorie.

3. Pour accéder au fichier et à la ligne contenant l'erreur dans l'onglet "Code", cliquez sur

   message d'erreur.

4. Dans la colonne Action, cliquez sur Correction suggérée.

5. Sélectionnez l'une des options suivantes : Appliquer ou Appliquer et relancer.

   • Pour copier le fichier de schéma généré du répertoire de sortie vers le répertoire d'entrée, cliquez sur Appliquer.
   • Pour copier le fichier de schéma généré du répertoire de sortie vers le répertoire d'entrée et ouvrir une fenêtre de réexécution, cliquez sur Appliquer et réexécuter.

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.

Tarifs

L'utilisation du traducteur SQL par lot n'engendre aucuns frais. 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.

Outils de ligne de commande pour les autres workflows de migration

Vous pouvez également envoyer un job de traduction par lot à l'aide d'un fichier de configuration de traduction avec la Google Cloud CLI (gcloud bq migration-workflows) ou avec l'outil de ligne de commande bq.

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

Créer un fichier de configuration de traduction

Un fichier de configuration de traduction définit le chemin d'accès aux fichiers sources, la destination de sortie, ainsi que les dialectes source et cible de votre traduction. Vous pouvez écrire ce fichier au format YAML ou JSON.

Remarque : Un fichier de configuration de traduction n'est pas la même chose qu'un fichier YAML de configuration. Un fichier de configuration de la traduction définit le job lui-même. Un fichier YAML de configuration permet de personnaliser la façon dont le traducteur transforme votre code SQL.

L'exemple suivant montre un fichier YAML de configuration de traduction pour une traduction de Teradata vers BigQuery :

tasks:
  translation_task:
    type: Teradata2BigQuery_Translation
    translationDetails:
      sourceTargetMapping:
      - sourceSpec:
          baseUri: gs://bq-translations/input
        targetSpec:
          relativePath: output
      targetBaseUri: gs://bq-translations
      targetTypes:
      - sql
      sourceEnvironment:
        defaultDatabase: default_db
        schemaSearchPath:
        - foo

L'exemple suivant montre un fichier JSON de configuration de la traduction pour une traduction de Teradata vers BigQuery :

{
  "tasks": {
    "translation_task": {
      "type": "Teradata2BigQuery_Translation",
      "translationDetails": {
        "sourceTargetMapping": [
          {
            "sourceSpec": {
              "literal": {
                "literalString": "sel 1",
                "relativePath": "my_input_1"
              },
              "encoding": "UTF-8"
            }
          },
          {
            "sourceSpec": {
              "literal": {
                "literalString": "sel 2",
                "relativePath": "my_input_2"
              },
              "encoding": "UTF-8"
            }
          }
        ],
        "targetReturnLiterals": [
          "sql/my_input_1",
          "sql/my_input_2"
        ]
      }
    }
  }
}

Envoyer et gérer des tâches de traduction

Utilisez l'un des outils de ligne de commande suivants pour envoyer et gérer vos jobs de traduction.

gcloud

Pour créer un job de traduction et exécuter le workflow, utilisez la commande suivante :

gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE

Pour créer et exécuter le workflow, puis revenir immédiatement avec un lien vers le workflow, ajoutez l'indicateur --async :

gcloud bq migration-workflows create --location=LOCATION --config-file=CONFIG_FILE --async

Pour lister vos jobs de traduction, utilisez la commande suivante :

gcloud bq migration-workflows list --location=LOCATION

Pour afficher les détails d'une tâche de traduction spécifique, utilisez la commande suivante :

gcloud bq migration-workflows describe projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Remplacez les éléments suivants :

• LOCATION : emplacement du projet Google Cloud qui exécute ce job de traduction.
• CONFIG_FILE : chemin d'accès à votre fichier de configuration de la traduction.
• PROJECT_ID : ID du projet Google Cloud exécutant cette tâche de traduction.
• WORKFLOW_ID : ID du job de traduction.

bq

Pour exécuter le job de traduction, utilisez la commande suivante :

bq mk --migration_workflow --location=LOCATION --config_file=CONFIG_FILE

Pour lister tous vos jobs de traduction, utilisez la commande suivante :

bq ls --migration_workflow --location=LOCATION

Pour afficher les détails d'une tâche de traduction spécifique, utilisez la commande suivante :

bq show --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Pour supprimer un job de traduction de la liste, utilisez la commande suivante :

bq rm --migration_workflow projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID

Remplacez les éléments suivants :

• LOCATION : emplacement du projet Google Cloud qui exécute ce job de traduction.
• CONFIG_FILE : chemin d'accès à votre fichier de configuration de la traduction.
• PROJECT_ID : ID du projet Google Cloud exécutant cette tâche de traduction.
• WORKFLOW_ID : ID du job de traduction.

Récupérer les fichiers de sortie

Pour télécharger les fichiers de résultat une fois le job terminé, utilisez gcloud storage cp comme décrit dans Récupérer les fichiers de résultat. Pour examiner le job dans la console Google Cloud , consultez Explorer le résultat de la traduction.

Étapes suivantes

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

• Présentation de la migration
• Évaluation de la migration
• Présentation du transfert de schéma et de données
• Pipelines de données
• Traduction SQL interactive
• Sécurité et gouvernance des données
• Outil de validation des données