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

Si votre emplacement est compatible, vous pouvez utiliser la fonctionnalité de règle de traduction (preview) pour personnaliser la façon dont le traducteur SQL interactif traduit le langage SQL.

Limites

Vous devez être connecté avec un compte Google pour utiliser le traducteur SQL interactif. La traduction SQL interactive n'est pas compatible avec l'utilisation des identités fédérées.

Avant de commencer

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.

Remarque : Cette API est activée automatiquement dans les projets créés après le 15 février 2022.

Autorisations et rôles

Cette section décrit les autorisations IAM (Identity and Access Management) dont vous avez besoin pour utiliser la traduction SQL interactive, ainsi que les rôles IAM prédéfinis qui accordent ces autorisations. La section décrit également les autorisations nécessaires pour définir des configurations de traduction supplémentaires.

Autorisations nécessaires pour l'utilisation du traducteur SQL interactif

Pour obtenir les autorisations nécessaires pour utiliser le traducteur interactif, demandez à votre administrateur de vous accorder le rôle IAM Éditeur MigrationWorkflow (roles/bigquerymigration.editor) sur la ressource parent. Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour utiliser le traducteur interactif. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour utiliser le traducteur interactif :

• bigquerymigration.workflows.create
• bigquerymigration.workflows.get

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

Autorisations permettant de définir des configurations de traduction supplémentaires

Vous pouvez définir des configurations de traduction supplémentaires à l'aide des champs ID de configuration de traduction et Emplacement source de la configuration de traduction dans les paramètres de traduction. Pour définir ces configurations de traduction, vous devez disposer des autorisations suivantes :

• bigquerymigration.workflows.get
• bigquerymigration.workflows.list

Le rôle IAM prédéfini suivant fournit les autorisations dont vous avez besoin pour définir des configurations de traduction supplémentaires :

• roles/bigquerymigration.viewer

Pour plus d'informations sur BigQuery IAM, consultez la page Contrôle des accès avec IAM.

Dialectes SQL pris en charge

Le traducteur SQL interactif de BigQuery peut traduire le dialecte SQL suivant 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
• IBM DB2 SQL
• MySQL SQL
• Oracle SQL, PL/SQL et Exadata
• PostgreSQL SQL
• Trino ou PrestoSQL
• Snowflake SQL
• SQL Server T-SQL
• SQLite
• Vertica SQL

Emplacements

La traduction SQL interactive n'est disponible que dans les emplacements de traitement suivants :

	Description de la région	Nom de la région	Détail
Asie-Pacifique
	Tokyo	asia-northeast1
	Mumbai	asia-south1
	Singapour	asia-southeast1
	Sydney	australia-southeast1
Europe
	UE (multirégional)	eu
	Varsovie	europe-central2
	Finlande	europe-north1	Faibles émissions de CO2
	Madrid	europe-southwest1	Faibles émissions de CO2
	Belgique	europe-west1	Faibles émissions de CO2
	Londres	europe-west2	Faibles émissions de CO2
	Francfort	europe-west3	Faibles émissions de CO2
	Pays-Bas	europe-west4	Faibles émissions de CO2
	Zurich	europe-west6	Faibles émissions de CO2
	Paris	europe-west9	Faibles émissions de CO2
	Turin	europe-west12
Amériques
	São Paulo	southamerica-east1	Faibles émissions de CO2
	États-Unis (multirégional)	us
	Iowa	us-central1	Faibles émissions de CO2
	Caroline du Sud	us-east1
	Virginie du Nord	us-east4
	Columbus, Ohio	us-east5
	Dallas	us-south1	Faibles émissions de CO2
	Oregon	us-west1	Faibles émissions de CO2
	Los Angeles	us-west2
	Salt Lake City	us-west3

La fonctionnalité de règle de traduction est disponible dans les emplacements de traitement suivants :

• us (États-Unis - multirégional)
• eu (UE - multirégional)
• us-central1 (Iowa)
• europe-west4 (Pays-Bas)

Traduire une requête en langage GoogleSQL

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

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

   Accéder à BigQuery

2. Dans le volet Éditeur, cliquez sur Plus, puis sélectionnez 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 Plus, puis sélectionnez 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, puis sélectionnez Désactiver la traduction SQL.

    Le volet Éditeur revient à un seul panneau.

Configurer le traducteur SQL interactif

Vous pouvez configurer le traducteur SQL interactif pour ajuster la façon dont il traduit votre code 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 une règle de traduction

Preview

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

Remarque : Les traductions SQL améliorées pour Gemini sont autorisées sans frais dans une quantité limitée, ce qui devrait suffire 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].

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. Cette fonctionnalité n'est disponible que dans certains emplacements.

Pour créer une règle de traduction SQL améliorée par Gemini, procédez comme suit :

Console

Pour créer une règle de traduction SQL améliorée par Gemini, procédez comme suit :

1. Après avoir exécuté une traduction interactive, cliquez sur Personnaliser.

   

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

   • Dans la requête Remplacer un modèle SQL par un autre, 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 le résultat de la traduction 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 du résultat de la traduction, décrivez 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 le résultat de la traduction.

3. Cliquez sur Aperçu.

4. Dans la boîte de dialogue Prévisualiser les modifications suggérées, examinez les modifications apportées par la traduction SQL améliorée par Gemini dans la sortie de traduction, en fonction de votre règle.

5. Facultatif : pour ajouter cette règle avec les traductions futures, cochez la case Ajouter une règle.

   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. Un fichier YAML de configuration peut accepter jusqu'à 10 règles de traduction et est soumis à des limites de taille de fichier de configuration.

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

YAML

Vous pouvez créer une règle de traduction SQL améliorée par Gemini en créant un fichier YAML de configuration et en l'important dans Cloud Storage.

Conditions requises

Le fichier YAML de la règle de traduction doit comporter le suffixe .ai_config.yaml. Par exemple, rules_1.ai_config.yaml.

Limites

• Vous ne pouvez appliquer qu'un seul fichier YAML de règle de traduction dans le traducteur SQL interactif.
• Chaque fichier YAML de règle de traduction peut contenir jusqu'à 10 règles et est soumis à des limites de taille de fichier de configuration.

Champs pris en charge

L'exemple suivant montre comment créer un fichier YAML de règle de traduction améliorée Gemini à l'aide d'une requête en langage naturel.

rewrite_target: TARGET
instruction: NL_PROMPT

Remplacez les éléments suivants :

• TARGET : indiquez si vous souhaitez appliquer la règle de traduction à votre code SQL d'entrée, SOURCE_SQL, ou au code SQL de sortie, TARGET_SQL (par défaut).
• NL_PROMPT : en langage naturel, décrivez une modification du code SQL cible. La traduction SQL améliorée par Gemini identifie la requête et effectue la modification spécifiée.

Vous pouvez également créer un fichier YAML de règles de traduction contenant plusieurs règles (jusqu'à 10). Chaque règle peut se composer d'une requête en langage naturel (instruction) qui décrit une règle et d'un ou plusieurs exemples pour remplacer un modèle SQL (input) par un autre (output). Une règle de traduction peut utiliser le champ instruction, un ou plusieurs champs examples, ou les deux types de champs pour décrire votre règle.

rewrite_target: TARGET
instruction: NL_PROMPT
translation_rules:
- instruction: NL_RULE_1
  examples:
  - input: RULE_1_INPUT_1
    output: RULE_1_OUTPUT_1
  - input: RULE_1_INPUT_2
    output: RULE_1_OUTPUT_2
- instruction: NL_RULE_2
  examples:
  - input: RULE_2_INPUT_1
    output: RULE_2_OUTPUT_1
…
…

Remplacez les éléments suivants :

• NL_RULE_1 (facultatif) : décrivez une règle de traduction en langage naturel.
• RULE_1_INPUT_1 (facultatif) : modèle SQL que vous souhaitez remplacer.

• RULE_1_OUTPUT_1 (facultatif) : modèle SQL attendu après le remplacement de input.

  Vous pouvez ajouter d'autres translation_rules (jusqu'à 10) et d'autres examples si nécessaire.

Pour obtenir des exemples de fichiers YAML de règles de traduction SQL améliorées par Gemini, consultez la section Exemples de fichiers YAML de règles de traduction.

Appliquer un fichier YAML de règle de traduction à votre prochaine traduction

Pour appliquer un fichier YAML de règle de traduction :

1. Dans l'éditeur de requête, cliquez sur Plus > Paramètres de traduction.
2. Dans le champ Emplacement source de la configuration de traduction, spécifiez le chemin d'accès au fichier YAML de la règle de traduction stocké dans un dossier Cloud Storage.
3. Cliquez sur Enregistrer.

Exemples de fichiers YAML de règles de traduction

Les exemples suivants sont des exemples de fichiers YAML de règles de traduction SQL améliorées par Gemini.

Exemple 1 : Spécifiez une fonction à remplacer par une autre.

translation_rules:
- instruction:  "Remove upper() function"
  examples:
  - input: "upper(X)"
    output: "X"

Exemple 2 : Spécifiez plusieurs règles de traduction dans un seul fichier YAML.

translation_rules:
- instruction:  "Remove upper() function"
  examples:
  - input: "upper(X)"
    output: "X"
- instruction: "Insert a comment at the head that explains each statement in detail."

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 Plus > 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 de configuration YAML 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 Plus > 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 de configuration 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

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;

Tarifs

L'utilisation du traducteur SQL interactif 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 :

• 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