Traduire des requêtes avec le traducteur SQL interactif

Ce document explique comment traduire une requête d'un autre dialecte SQL en une requête GoogleSQL à l'aide de la traduction SQL interactive de BigQuery. La traduction SQL interactive peut vous aider à réduire le temps et les efforts de migration des charges de travail vers BigQuery. Ce document est destiné aux utilisateurs qui connaissent déjà la Google Cloud console.

Vous pouvez utiliser la fonctionnalité de règle de traduction pour personnaliser la façon dont le traducteur SQL interactif traduit le langage SQL.

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

Pour obtenir la liste des emplacements de traitement compatibles, consultez la section 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 la section Activer les traductions SQL.

Autorisations requises

Pour obtenir les autorisations nécessaires pour créer des tâches 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 tâches de migration : lecteur MigrationWorkflow (roles/bigquerymigration.viewer)
• Envoyer des tâches de migration : éditeur MigrationWorkflow (roles/bigquerymigration.editor)
• Accéder aux buckets Cloud Storage pour les entrées et les fichiers : Administrateur des objets de l'espace de stockage (roles/storage.objectAdmin) sur le 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 tâches 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 tâches 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.

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

Lors de la traduction de SQL d'un dialecte source vers BigQuery, certaines fonctions peuvent ne pas avoir d'équivalent direct. Pour résoudre ce problème, BigQuery Migration Service (et la communauté BigQuery au sens large) fournit des fonctions définies par l'utilisateur 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 n'est pas recommandé 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 importantes dans vos requêtes de production si la logique d'une UDF 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 si elles 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 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 ensemble de données. Vous bénéficiez ainsi d'un contrôle total sur 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 interactive n'est disponible que dans certains emplacements de traitement. Pour plus d'informations, consultez la section Emplacements.

Les configurations de traduction basées sur Gemini ne sont disponibles que dans des emplacements de traitement spécifiques. Pour en savoir plus, consultez la section Emplacements des points de terminaison des modèles Google.

Traduire une requête en langage GoogleSQL

Pour traduire une requête en langage GoogleSQL, procédez comme suit :

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

   Accéder à BigQuery

2. Dans le volet Éditeur, cliquez sur Outils > Paramètres de traduction.

3. Pour le champ Dialecte source, sélectionnez le dialecte SQL que vous souhaitez traduire.

4. Facultatif. Dans le champ Emplacement du 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 d'emplacement, sélectionnez la région eu.

5. Cliquez sur Enregistrer.

6. Dans le volet Éditeur, cliquez sur Outils > Activer la traduction SQL.

   Le volet Éditeur se divise en deux volets.

7. Dans le volet de gauche, saisissez la requête que vous souhaitez traduire.

8. Cliquez sur Traduire.

   BigQuery traduit votre requête en langage GoogleSQL et l'affiche dans le volet de droite. Par exemple, la capture d'écran suivante montre le langage SQL Teradata traduit :

   

9. Facultatif : Pour exécuter la requête GoogleSQL traduite, cliquez sur Exécuter.

10. Facultatif : Pour revenir à l'éditeur SQL, cliquez sur Plus > Désactiver la traduction SQL.

    Le volet Éditeur revient à un seul panneau.

Utiliser Gemini avec le traducteur SQL interactif

Vous pouvez configurer le traducteur SQL interactif pour ajuster la façon dont il traduit votre SQL source. Pour ce faire, vous pouvez fournir vos propres règles à utiliser avec Gemini dans un fichier de configuration YAML, ou fournir un fichier de configuration YAML contenant des métadonnées d'objet SQL ou des informations de mappage d'objets.

Créer et appliquer des règles de traduction améliorées par Gemini

Remarque : Pour obtenir de l'aide et envoyer des commentaires sur les fonctionnalités en preview, contactez [e-mail].

Vous pouvez personnaliser la façon dont le traducteur SQL interactif traduit le langage SQL en créant des règles de traduction. Le traducteur SQL interactif ajuste ses traductions en fonction des règles de traduction SQL améliorées de Gemini que vous lui attribuez, ce qui vous permet de personnaliser les résultats de traduction en fonction de vos besoins de migration.

Pour créer une règle de traduction SQL améliorée par Gemini, vous pouvez la créer dans la console ou créer un fichier de configuration YAML et l'importer dans Cloud Storage.

Console

Pour créer une règle de traduction SQL améliorée par Gemini pour le SQL d'entrée, écrivez une requête SQL d'entrée dans l'éditeur de requête, puis cliquez sur AIDE > Personnaliser. (Aperçu)

De même, pour créer une règle de traduction SQL améliorée par Gemini pour le SQL de sortie, exécutez une traduction interactive, puis cliquez sur AIDE > Personnaliser cette traduction.

Lorsque le menu Personnaliser s'affiche, procédez comme suit.

1. Utilisez l'une des requêtes suivantes, ou les deux, pour créer une règle de traduction :

   • Dans la requête Rechercher et remplacer un modèle, spécifiez un modèle SQL que vous souhaitez remplacer dans le champ Remplacer, ainsi qu'un modèle SQL à remplacer. dans le champ Par.

     Un modèle SQL peut contenir un nombre illimité d'instructions, de clauses ou de fonctions dans un script SQL. Lorsque vous créez une règle à l'aide de cette requête, la traduction SQL améliorée par Gemini identifie toutes les instances de ce modèle SQL dans la requête SQL et les remplace de manière dynamique par un autre modèle SQL. Par exemple, vous pouvez utiliser cette requête pour créer une règle qui remplace toutes les occurrences de months_between (X,Y) par date_diff(X,Y,MONTH).

   • Dans le champ Décrire une modification de la sortie, saisissez une modification du résultat de la traduction SQL en langage naturel.

     Lorsque vous créez une règle à l'aide de cette requête, la traduction SQL améliorée par Gemini identifie la requête et effectue la modification spécifiée dans la requête SQL.

2. Cliquez sur Aperçu.

3. Dans la boîte de dialogue Suggestions générées par Gemini, examinez les modifications apportées par la traduction SQL améliorée par Gemini à la requête SQL en fonction de votre règle.

   

4. Facultatif : pour ajouter cette règle avec les traductions futures, cochez la case Enregistrer cette requête.

   Les règles sont enregistrées dans le fichier YAML de configuration par défaut, ou __default.ai_config.yaml. Ce fichier YAML de configuration est enregistré dans le dossier Cloud Storage, comme spécifié dans le champ Emplacement source de la configuration de traduction des paramètres de traduction. Si le Emplacement source de la configuration de traduction n'est pas déjà défini, un navigateur de dossiers s'affiche et vous permet d'en sélectionner un. Un fichier YAML de configuration est soumis à des limites de taille de fichier de configuration.

5. Pour appliquer les modifications suggérées à la requête SQL, cliquez sur Appliquer.

YAML

Pour créer une règle de traduction SQL améliorée par Gemini, vous pouvez créer un fichier YAML de configuration basé sur Gemini et l'importer dans Cloud Storage. Pour en savoir plus, consultez la section Créer un fichier YAML de configuration basé sur Gemini.

Une fois que vous avez importé une règle de traduction SQL améliorée par Gemini dans Cloud Storage, vous pouvez l'appliquer en procédant comme suit :

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

   Accéder à BigQuery

2. Dans l'éditeur de requête, cliquez sur Outils > Paramètres de traduction.

3. Dans le champ Emplacement source de la configuration de traduction, spécifiez le chemin d'accès au fichier YAML basé sur Gemini stocké dans un dossier Cloud Storage.

4. Cliquez sur Enregistrer.

   Une fois l'enregistrement effectué, exécutez une traduction interactive. Le traducteur interactif suggère des modifications à vos traductions en fonction des règles de votre fichier YAML de configuration, le cas échéant.

Si une suggestion Gemini est disponible pour l'entrée en fonction de votre règle, la boîte de dialogue Prévisualiser les modifications suggérées s'affiche et indique les modifications possibles de l'entrée de traduction. (Aperçu)

Si une suggestion Gemini est disponible pour le résultat en fonction de votre règle, une bannière de notification s'affiche dans l'éditeur de code. Pour examiner et appliquer ces suggestions, procédez comme suit :

1. Cliquez sur Aide > Afficher les suggestions de chaque côté de l' éditeur de code pour revenir aux modifications suggérées de la requête correspondante.

   

2. Dans la boîte de dialogue Suggestions générées par Gemini, examinez les modifications apportées par Gemini à la requête SQL en fonction de votre règle de traduction.

3. Pour appliquer les modifications suggérées au résultat de la traduction, cliquez sur Appliquer.

Mettre à jour le fichier YAML de configuration basé sur Gemini

Pour mettre à jour un fichier YAML de configuration existant, procédez comme suit :

1. Dans la boîte de dialogue Suggestions générées dans Gemini, cliquez sur Afficher le fichier de configuration des règles Gemini.

2. Lorsque l'éditeur de configuration s'affiche, sélectionnez le fichier YAML de configuration que vous souhaitez modifier.

3. Apportez la modification, puis cliquez sur Enregistrer.

4. Fermez l'éditeur YAML en cliquant sur OK.

5. Exécutez une traduction interactive pour appliquer la règle mise à jour.

Expliquer une traduction

Aperçu

Ce produit ou cette fonctionnalité est soumis aux "Conditions des offres pré-DG" de la section "Conditions d'utilisation 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 : Avec les traductions SQL améliorées par Gemini, vous pouvez générer une explication textuelle de vos scripts à l’aide du modèle Gemini. Les traductions SQL améliorées par Gemini sont autorisées sans frais dans une quantité limitée. Cette utilisation est suffisante pour la plupart des projets de migration. Pour demander une augmentation de cette limite, ou pour obtenir de l'aide et envoyer des commentaires sur cette fonctionnalité en preview, contactez [e-mail].

Après avoir exécuté une traduction interactive, vous pouvez demander une explication textuelle générée par Gemini. Le texte généré inclut un résumé de la requête SQL traduite. Gemini identifie également les différences et les incohérences de traduction entre la requête SQL source et la requête GoogleSQL traduite.

Pour obtenir une explication de la traduction SQL générée par Gemini, procédez comme suit :

1. Pour créer une explication de la traduction SQL générée par Gemini, cliquez sur Aide, puis sur Expliquer cette traduction.

   

Traduire avec un ID de configuration de traduction par lot

Vous pouvez exécuter une requête interactive avec les mêmes configurations de traduction qu'une tâche de traduction par lot en fournissant un ID de configuration de traduction par lot.

1. Dans l'éditeur de requête, cliquez sur Outils > Paramètres de traduction.

2. Dans le champ ID de configuration de traduction, indiquez un ID de configuration de traduction par lot pour appliquer la même configuration de traduction à partir d'une tâche de migration par lot BigQuery terminée.

   Pour trouver l'ID de configuration de la traduction par lot d'un job, sélectionnez une tâche de traduction par lot sur la page Traduction SQL, puis cliquez sur l'onglet Configuration de la traduction. L'ID de configuration de la traduction par lot est répertorié en tant que Nom de ressource.

3. Cliquez sur Enregistrer.

Traduire avec des configurations supplémentaires

Vous pouvez exécuter une requête interactive avec des configurations de traduction supplémentaires en spécifiant des fichiers YAML de configuration stockés dans un dossier Cloud Storage. Les configurations de traduction peuvent inclure des métadonnées d'objet SQL ou des informations de mappage d'objets à partir de la base de données source, ce qui peut améliorer la qualité de la traduction. Par exemple, incluez des informations ou des schémas LDD de la base de données source pour améliorer la qualité de la traduction SQL interactive.

Pour spécifier des configurations de traduction en fournissant un emplacement pour les fichiers sources de la configuration de traduction, procédez comme suit :

1. Dans l'éditeur de requête, cliquez sur Outils > Paramètres de traduction.

2. Dans le champ Emplacement source de la configuration de traduction, spécifiez le chemin d'accès aux fichiers de configuration de traduction stocké dans un dossier Cloud Storage.

   La traduction SQL interactive de BigQuery accepte les fichiers ZIP de métadonnées contenant des métadonnées de traduction et le mappage de noms d'objets. Pour en savoir plus sur l'importation de fichiers dans Cloud Storage, consultez la page Importer des objets à partir d'un système de fichiers.

3. Cliquez sur Enregistrer.

Limites de taille des fichiers de configuration

Lorsque vous utilisez un fichier de configuration de traduction avec le traducteur SQL interactif de BigQuery, le fichier de métadonnées compressé ou le fichier de configuration YAML doit être inférieur à 50 Mo. Si la taille du fichier dépasse 50 Mo, le traducteur interactif ignore ce fichier de configuration lors de la traduction et génère un message d'erreur semblable à celui-ci :

CONFIG ERROR: Skip reading file "gs://metadata-file.zip". File size (150,000,000 bytes) exceeds limit (50 MB).

Une méthode permettant de réduire la taille du fichier de métadonnées consiste à utiliser les options --database ou --schema pour n'extraire que les métadonnées de bases de données ou de schémas pertinents pour les requêtes d'entrée de traduction. Pour en savoir plus sur l'utilisation de ces options lorsque vous générez des fichiers de métadonnées, consultez la page Options globales.

Résoudre les erreurs de traduction

Les erreurs suivantes sont fréquentes lors de l'utilisation du traducteur SQL interactif.

Problèmes de traduction RelationNotFound ou AttributeNotFound

Après avoir traduit une requête à l'aide du traducteur SQL interactif, vous pouvez rencontrer une erreur de traduction avec l'erreur RelationNotFound ou AttributeNotFound.

Pour trouver les traductions ayant échoué, accédez à la page Détails de la traduction et ouvrez l'onglet Messages du journal.

Pour garantir une traduction plus précise, vous pouvez saisir les instructions LDD (langage de définition de données) pour toutes les tables utilisées dans une requête avant la requête elle-même. Par exemple, si vous souhaitez traduire la requête Amazon Redshift select table1.field1, table2.field1 from table1, table2 where table1.id = table2.id;, vous devez saisir les instructions SQL suivantes dans le traducteur SQL interactif :

create table schema1.table1 (id int, field1 int, field2 varchar(16));
create table schema1.table2 (id int, field1 varchar(30), field2 date);

select table1.field1, table2.field1
from table1, table2
where table1.id = table2.id;

Résoudre les problèmes de traduction avec Gemini

Aperçu

Ce produit ou cette fonctionnalité est soumis aux "Conditions des offres pré-DG" de la section "Conditions d'utilisation 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 envoyer des commentaires ou demander 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 tenter de résoudre ces problèmes en procédant comme suit.

1. Accédez à la page Détails de la traduction et ouvrez l'onglet Messages du journal.

2. Cliquez sur la requête contenant le message RelationNotFound ou AttributeNotFound dans la colonne Catégorie.

3. Cliquez sur Correction suggérée.

4. Cliquez sur Appliquer.

5. Cliquez sur Traduire pour retraduire la requête.

Tarifs

L'utilisation du traducteur SQL interactif est sans 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.

É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
• Traduction SQL par lot
• Pipelines de données
• Sécurité et gouvernance des données
• Outil de validation des données