Transformer des traductions SQL à l'aide de fichiers de configuration YAML

Ce document explique comment utiliser des fichiers de configuration YAML pour transformer le code SQL lors de sa migration vers BigQuery. Il fournit des consignes pour créer vos propres fichiers de configuration YAML et des exemples de différentes transformations de traduction compatibles avec cette fonctionnalité.

Lorsque vous utilisez le traducteur SQL interactif de BigQuery, l'API BigQuery Migration ou effectuez une traduction SQL par lot, vous pouvez fournir des fichiers de configuration YAML pour modifier une traduction de requête SQL. L'utilisation de fichiers YAML de configuration permet de personnaliser davantage la traduction des requêtes SQL à partir de votre base de données source.

Vous pouvez spécifier un fichier YAML de configuration à utiliser dans une traduction SQL de différentes manières :

Le traducteur SQL interactif, l'API BigQuery Migration, le traducteur SQL par lot et le client Python de traduction par lot permettent d'utiliser plusieurs fichiers de configuration YAML dans un même job de traduction. Pour en savoir plus, consultez la section Appliquer plusieurs configurations YAML.

Configuration des exigences de fichier YAML

Avant de créer un fichier YAML de configuration, consultez les informations suivantes pour vous assurer que votre fichier YAML est compatible avec le service de migration BigQuery :

  • Vous devez importer les fichiers de configuration YAML dans le répertoire racine du bucket Cloud Storage qui contient vos fichiers d'entrée de traduction SQL. Pour en savoir plus sur la création de buckets et l'importation de fichiers dans Cloud Storage, consultez les sections Créer des buckets et Importer des objets à partir d'un système de fichiers.
  • La taille d'un seul fichier YAML de configuration ne doit pas dépasser 1 Mo.
  • La taille totale de tous les fichiers de configuration YAML utilisés dans un seul job de traduction SQL ne doit pas dépasser 4 Mo.
  • Si vous utilisez la syntaxe regex pour la mise en correspondance des noms, utilisez RE2/J.
  • Tous les noms de fichiers de configuration YAML doivent inclure une extension .config.yaml, par exemple change-case.config.yaml.
    • config.yaml seul n'est pas un nom valide pour le fichier de configuration.

Consignes pour créer un fichier YAML de configuration

Cette section fournit des instructions générales pour créer un fichier YAML de configuration :

Chaque fichier de configuration doit contenir un en-tête spécifiant le type de configuration. Le type object_rewriter permet de spécifier des traductions SQL dans un fichier YAML de configuration. L'exemple suivant utilise le type object_rewriter pour transformer la casse d'un nom :

type: object_rewriter
global:
  case:
    all: UPPERCASE

Sélection d'entités

Pour effectuer des transformations spécifiques à l'entité, spécifiez l'entité dans le fichier de configuration. Toutes les propriétés match sont facultatives. N'utilisez que les propriétés match nécessaires à une transformation. Le YAML de configuration suivante expose les propriétés à mettre en correspondance afin de sélectionner des entités spécifiques :

match:
  database: <literal_name>
  schema: <literal_name>
  relation: <literal_name>
  attribute: <literal_name>
  databaseRegex: <regex>
  schemaRegex: <regex>
  relationRegex: <regex>
  attributeRegex: <regex>

Description de chaque propriété match :

  • database ou db: composant project_id
  • schema : composant de l'ensemble de données
  • relation : composant de la table
  • attribute : composant de la colonne. Uniquement valide pour la sélection d'attributs
  • databaseRegex ou dbRegex: correspond à une propriété database avec une expression régulière (Aperçu).
  • schemaRegex : met en correspondance les propriétés schema et les expressions régulières (preview).
  • relationRegex : correspond aux propriétés relation avec des expressions régulières (preview).
  • attributeRegex : correspond aux propriétés attribute avec des expressions régulières. Uniquement valide pour la sélection d'attributs (preview).

Par exemple, le fichier YAML de configuration suivant spécifie les propriétés match pour sélectionner la table testdb.acme.employee en vue d'une transformation de table temporaire.

type: object_rewriter
relation:
-
  match:
    database: testdb
    schema: acme
    relation: employee
  temporary: true

Vous pouvez utiliser les propriétés databaseRegex, schemaRegex, relationRegex et attributeRegex pour spécifier des expressions régulières afin de sélectionner un sous-ensemble d'entités. L'exemple suivant remplace toutes les relations du schéma tmp_schema dans testdb par des noms temporaires, à condition que leur nom commence par tmp_:

type: object_rewriter
relation:
-
  match:
    schema: tmp_schema
    relationRegex: "tmp_.*"
  temporary: true

Les propriétés littérales et regex sont mises en correspondance sans distinction de casse. Vous pouvez appliquer la correspondance sensible à la casse en utilisant regex avec une option i désactivée, comme illustré dans l'exemple suivant :

match:
  relationRegex: "(?-i:<actual_regex>)"

Vous pouvez également spécifier des entités complètes à l'aide d'une syntaxe de chaîne courte équivalente. Une syntaxe de chaîne courte attend exactement 3 segments de nom (pour la sélection de relation) ou 4 (pour la sélection d'attributs) délimités par des points, comme dans l'exemple testdb.acme.employee. Les segments sont ensuite interprétés en interne comme s'ils étaient transmis en tant que database, schema, relation et attribute, respectivement. Cela signifie que les noms sont mis en correspondance de manière littérale. Par conséquent, les expressions régulières ne sont pas autorisées dans la syntaxe abrégée. L'exemple suivant montre comment utiliser la syntaxe de chaîne courte pour spécifier une entité complète dans un fichier YAML de configuration :

type: object_rewriter
relation:
-
  match : "testdb.acme.employee"
  temporary: true

Si le nom d'une table contient un point, vous ne pouvez pas le spécifier à l'aide d'une syntaxe courte. Dans ce cas, vous devez utiliser une correspondance d'objet. L'exemple suivant remplace la table testdb.acme.stg.employee par une table temporaire :

type: object_rewriter
relation:
-
  match:
    database: testdb
    schema: acme
    relation: stg.employee
  temporary: true

Le fichier de configuration YAML accepte key comme alias de match.

Base de données par défaut

Certains dialectes SQL d'entrée, y compris Teradata, ne sont pas compatibles avec database-name dans le nom complet. Dans ce cas, le moyen le plus simple de faire correspondre des entités consiste à omettre la propriété database dans match.

Toutefois, vous pouvez définir la propriété default_database du service de migration BigQuery et utiliser cette base de données par défaut dans match.

Types d'attributs cibles compatibles

Vous pouvez utiliser le fichier de configuration YAML pour effectuer des transformations de type d'attribut, où vous transformez le type de données d'une colonne du type source au type cible. Le fichier YAML de configuration accepte les types de cibles suivants :

  • BOOLEAN
  • TINYINT
  • SMALLINT
  • INTEGER
  • BIGINT
  • FLOAT
  • DOUBLE
  • NUMERIC (accepte la précision et l'échelle facultatives, comme NUMERIC(18, 2))
  • TIME
  • TIMETZ
  • DATE
  • DATETIME
  • TIMESTAMP
  • TIMESTAMPTZ
  • CHAR (accepte la précision facultative, telle que CHAR(42))
  • VARCHAR (accepte la précision facultative, telle que VARCHAR(42))

Exemples de fichiers YAML de configuration

Cette section fournit des exemples permettant de créer divers fichiers YAML de configuration à utiliser avec vos traductions SQL. Chaque exemple décrit la syntaxe YAML permettant de transformer votre traduction SQL de manière spécifique, ainsi qu'une brève description. Chaque exemple fournit également le contenu d'un fichier teradata-input.sql ou hive-input.sql et d'un fichier bq-output.sql afin que vous puissiez comparer les effets d'une configuration YAML sur une requête de traduction SQL BigQuery.

Les exemples suivants utilisent Teradata ou Hive comme dialecte SQL d'entrée et SQL BigQuery comme dialecte de sortie. Les exemples suivants utilisent également testdb comme base de données par défaut et testschema comme chemin d'accès de recherche du schéma.

Modifier la casse du nom de l'objet

La configuration YAML suivante modifie les majuscules ou les minuscules des noms d'objet :

type: object_rewriter
global:
  case:
    all: UPPERCASE
    database: LOWERCASE
    attribute: LOWERCASE

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
      create table x(a int);
      select * from x;
bq-output.sql 
      CREATE TABLE testdb.TESTSCHEMA.X
      (
        a INT64
      )
      ;
      SELECT
          X.a
        FROM
          testdb.TESTSCHEMA.X
      ;

Rendre une table temporaire

La configuration YAML suivante modifie une table standard en table temporaire :

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    temporary: true

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
    create table x(a int);
bq-output.sql 
    CREATE TEMPORARY TABLE x
    (
      a INT64
    )
    ;

Rendre une table éphémère

La configuration YAML suivante convertit une table standard en table éphémère avec un délai d'expiration de 60 secondes.

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    ephemeral:
      expireAfterSeconds: 60

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
    create table x(a int);
bq-output.sql 
    CREATE TABLE testdb.testschema.x
    (
      a INT64
    )
    OPTIONS(
      expiration_timestamp=timestamp_add(current_timestamp(), interval 60 SECOND)
    );

Définir l'expiration de la partition

La configuration YAML suivante modifie le délai d'expiration d'une table partitionnée sur un jour :

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    partitionLifetime:
      expireAfterSeconds: 86400

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
    create table x(a int, b int) partition by (a);
bq-output.sql 
    CREATE TABLE testdb.testschema.x
    (
      a INT64,
      b INT64
    )
    CLUSTER BY a
    OPTIONS(
      partition_expiration_days=1
    );

Modifier l'emplacement ou le format externe d'un tableau

La configuration YAML suivante modifie l'emplacement et la formation externes d'une table :

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    external:
      locations: "gs://path/to/department/files"
      format: ORC

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
    create table x(a int);
bq-output.sql 
    CREATE EXTERNAL TABLE testdb.testschema.x
    (
      a INT64
    )
    OPTIONS(
      format='ORC',
      uris=[
        'gs://path/to/department/files'
      ]
    );

Définir ou modifier la description d'une table

La configuration YAML suivante définit la description d'une table :

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    description:
      text: "Example description."

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
    create table x(a int);
bq-output.sql 
    CREATE TABLE testdb.testschema.x
    (
      a INT64
    )
    OPTIONS(
      description='Example description.'
    );

Définir ou modifier le partitionnement de la table

La configuration YAML suivante modifie le schéma de partitionnement d'une table :

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    partition:
      simple:
        add: [a]
  -
    match: "testdb.testschema.y"
    partition:
      simple:
        remove: [a]

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
    create table x(a date, b int);
    create table y(a date, b int) partition by (a);
bq-output.sql 
    CREATE TABLE testdb.testschema.x
    (
      a DATE,
      b INT64
    )
    PARTITION BY a;
    CREATE TABLE testdb.testschema.y
    (
      a DATE,
      b INT64
    )
    ;

Définir ou modifier le clustering de tables

La configuration YAML suivante modifie le schéma de clustering d'une table :

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    clustering:
      add: [a]
  -
    match: "testdb.testschema.y"
    clustering:
      remove: [b]

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

hive-input.sql 
    create table x(a int, b int);
    create table y(a int, b int) clustered by (b) into 16 buckets;
bq-output.sql 
    CREATE TABLE testdb.testschema.x
    (
      a INT64,
      b INT64
    )
    CLUSTER BY a;
    CREATE TABLE testdb.testschema.y
    (
      a INT64,
      b INT64
    )
    ;

Modifier le type d'un attribut de colonne

La configuration YAML suivante modifie le type de données d'un attribut d'une colonne :

type: object_rewriter
attribute:
  -
    match:
      database: testdb
      schema: testschema
      attributeRegex: "a+"
    type:
      target: NUMERIC(10,2)

Vous pouvez transformer le type de données source en l'un des types d'attributs cibles compatibles.

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
    create table x(a int, b int, aa int);
bq-output.sql 
    CREATE TABLE testdb.testschema.x
    (
      a NUMERIC(31, 2),
      b INT64,
      aa NUMERIC(31, 2)
    )
    ;

Ajouter une connexion au lac de données externe

La configuration YAML suivante marque la table source en tant que table externe qui pointe vers des données stockées dans un lac de données externe, spécifiée par une connexion de lac de données.

type: object_rewriter
relation:
-
  key: "testdb.acme.employee"
  external:
    connection_id: "connection_test"

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

hive-input.sql 
    CREATE TABLE x
    (
      a VARCHAR(150),
      b INT
    );
bq-output.sql 
    CREATE EXTERNAL TABLE x
    (
      a STRING,
      b INT64
    )
    WITH CONNECTION `connection_test`
    OPTIONS(
    );

Modifier l'encodage des caractères d'un fichier d'entrée

Par défaut, le service de migration BigQuery tente de détecter automatiquement l'encodage des caractères des fichiers d'entrée. Dans les cas où BigQuery Migration Service peut mal identifier l'encodage d'un fichier, vous pouvez utiliser un fichier de configuration YAML pour spécifier explicitement l'encodage des caractères.

La configuration YAML suivante spécifie l'encodage de caractères explicite du fichier d'entrée comme ISO-8859-1.

type: experimental_input_formats
formats:
- source:
    pathGlob: "*.sql"
  contents:
    raw:
      charset: iso-8859-1

Conversion de type global

La configuration YAML suivante remplace un type de données par un autre dans tous les scripts et spécifie un type de données source à éviter dans le script transcompilé. Cette configuration est différente de celle de la section Changer le type d'un attribut de colonne, où seul le type de données d'un seul attribut est modifié.

BigQuery accepte les conversions des types de données suivants :

  • De DATETIME à TIMESTAMP
  • De TIMESTAMP à DATETIME (accepte un fuseau horaire facultatif)
  • De TIMESTAMP WITH TIME ZONE à DATETIME (accepte un fuseau horaire facultatif)
  • De CHAR à VARCHAR

Dans l'exemple suivant, le fichier de configuration YAML convertit le type de données TIMESTAMP en DATETIME.

type: experimental_object_rewriter
global:
  typeConvert:
    timestamp: DATETIME

Dans des dialectes tels que Teradata, les fonctions liées à la date et à l'heure, telles que current_date, current_time ou current_timestamp, renvoient des codes temporels basés sur le fuseau horaire configuré, local ou par session. BigQuery, en revanche, renvoie toujours des codes temporels en UTC. Pour garantir un comportement cohérent entre les deux dialectes, il est nécessaire de configurer le fuseau horaire en conséquence.

Dans l'exemple suivant, le fichier de configuration YAML convertit un type de données TIMESTAMP et TIMESTAMP WITH TIME ZONE en DATETIME, avec le fuseau horaire cible défini sur Europe/Paris.

type: experimental_object_rewriter
global:
  typeConvert:
    timestamp:
      target: DATETIME
      timezone: Europe/Paris
    timestamptz:
      target: DATETIME
      timezone: Europe/Paris

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
      create table x(a timestamp);
      select a from x where a > current_timestamp(0);
bq-output.sql 
      CREATE TABLE x
      (
        a TIMESTAMP
      )
      ;
      SELECT
          x.a
        FROM
          test.x
        WHERE x.a > datetime_trunc(current_datetime('Europe/Paris'), SECOND)
      ;

Sélectionner la modification du relevé

La configuration YAML suivante modifie la projection en étoile, GROUP BY, et les clauses ORDER BY dans les instructions SELECT.

starProjection accepte les configurations suivantes :

  • ALLOW
  • PRESERVE (par défaut)
  • EXPAND

groupBy et orderBy acceptent les configurations suivantes :

  • EXPRESSION
  • ALIAS
  • INDEX

Dans l'exemple suivant, le fichier de configuration YAML configure la projection d'étoiles sur EXPAND.

type: experimental_statement_rewriter
select:
  starProjection: EXPAND

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
      create table x(a int, b TIMESTAMP);
      select * from x;
bq-output.sql 
      CREATE TABLE x
      (
        a INT64,
        b DATETIME
      )
      ;
      SELECT
          x.a
          x.b
        FROM
          x
      ;

Spécification des fonctions définies par l'utilisateur

Le fichier de configuration YAML suivant spécifie la signature des fonctions définies par l'utilisateur (UDF) utilisées dans les scripts sources. Tout comme les fichiers ZIP de métadonnées, les définitions des UDF peuvent aider à produire une traduction plus précise des scripts d'entrée.

type: metadata
udfs:
  - "date parse_short_date(dt int)"

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
      create table x(dt int);
      select parse_short_date(dt) + 1 from x;
bq-output.sql 
      CREATE TABLE x
      (
        dt INT64
      )
      ;
      SELECT
          date_add(parse_short_date(x.dt), interval 1 DAY)
        FROM
          x
      ;

Définir le niveau de rigueur de la précision décimale

Par défaut, le service de migration BigQuery augmente la précision numérique à la plus haute précision disponible pour une échelle donnée. La configuration YAML suivante ignore ce comportement en configurant la rigueur de la précision pour conserver la précision décimale de l'instruction source.

type: experimental_statement_rewriter
common:
  decimalPrecision: STRICT

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
      create table x(a decimal(3,0));
bq-output.sql 
      CREATE TABLE x
      (
        a NUMERIC(3)
      )
      ;

Mappage des noms de sortie

Vous pouvez utiliser un fichier de configuration YAML pour mapper les noms d'objets SQL. Vous pouvez modifier différentes parties du nom en fonction de l'objet mappé.

Mappage des noms statiques

Utilisez le mappage des noms statiques pour mapper le nom d'une entité. Si vous souhaitez ne modifier que certaines parties du nom tout en conservant les autres parties, n'incluez que les parties à modifier.

La configuration YAML suivante remplace le nom de la table my_db.my_schema.my_table par my_new_db.my_schema.my_new_table.

type: experimental_object_rewriter
relation:
-
  match: "my_db.my_schema.my_table"
  outputName:
    database: "my_new_db"
    relation: "my_new_table"

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
      create table my_db.my_schema.my_table(a int);
bq-output.sql 
      CREATE TABLE my_new_db.my_schema.my_new_table
      (
        a INT64
      )

Vous pouvez utiliser la mise en correspondance de noms statiques pour mettre à jour la région utilisée par les noms dans les fonctions publiques définies par l'utilisateur.

L'exemple suivant remplace les noms de la UDF définie par l'utilisateur bqutil.fn à partir de la multirégion us par défaut par la région europe_west2:

type: experimental_object_rewriter
function:
-
  match:
    database: bqutil
    schema: fn
  outputName:
    database: bqutil
    schema: fn_europe_west2

Mappage des noms dynamiques

Utilisez le mappage des noms dynamique pour modifier plusieurs objets en même temps et créer des noms en fonction des objets mappés.

La configuration YAML suivante modifie le nom de toutes les tables en ajoutant le préfixe stg_ à celles qui appartiennent au schéma staging, puis déplace ces tables vers le schéma production.

type: experimental_object_rewriter
relation:
-
  match:
    schema: staging
  outputName:
    schema: production
    relation: "stg_${relation}"

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
      create table staging.my_table(a int);
bq-output.sql 
      CREATE TABLE production.stg_my_table
      (
        a INT64
      )
      ;

Spécifier le chemin de recherche de base de données et de schéma par défaut

La configuration YAML suivante spécifie une base de données par défaut et un chemin de recherche de schéma.

type: environment
session:
  defaultDatabase: myproject
  schemaSearchPath: [myschema1, myschema2]

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
      SELECT * FROM database.table
      SELECT * FROM table1
bq-output.sql 
      SELECT * FROM myproject.database.table.
      SELECT * FROM myproject.myschema1.table1

Réécriture global des noms de sortie

La configuration YAML suivante modifie les noms de sortie de tous les objets (base de données, schéma, relation et attributs) du script conformément aux règles configurées.

type: experimental_object_rewriter
global:
  outputName:
    regex:
      - match: '\s'
        replaceWith: '_'
      - match: '>='
        replaceWith: 'gte'
      - match: '^[^a-zA-Z_].*'
        replaceWith: '_$0'

Une traduction SQL avec ce fichier YAML de configuration peut se présenter comme suit :

teradata-input.sql 
      create table "test special chars >= 12"("42eid" int, "custom column" varchar(10));
bq-output.sql 
      CREATE TABLE test_special_chars_employees_gte_12
      (
        _42eid INT64,
        custom_column STRING
      )
      ;

Optimiser et améliorer les performances du code SQL traduit

Des transformations facultatives peuvent être appliquées au code SQL traduit afin d'introduire des modifications pouvant améliorer la requête en termes de performances ou de coûts. Ces optimisations sont strictement dépendantes du cas et doivent être évaluées par rapport à la sortie SQL non modifiée pour évaluer leur effet réel sur les performances.

Le fichier de configuration YAML suivant permet d'activer des transformations facultatives. La configuration accepte une liste d'optimisations et, pour les optimisations qui acceptent des paramètres, une section avec des valeurs de paramètre facultatives.

type: experimental_optimizer
transformations:
  - name: PRECOMPUTE_INDEPENDENT_SUBSELECTS
  - name: REWRITE_CTE_TO_TEMP_TABLE
    parameters:
      threshold: 1
Optimisation Paramètre facultatif Description
PRECOMPUTE_INDEPENDENT_SUBSELECTS scope: [PREDICATE, PROJECTION] Réécrit la requête en ajoutant une instruction DECLARE pour remplacer une expression dans les clauses PREDICATE ou PROJECTION par une variable précalculée. Cela sera identifié comme un prédicat statique permettant de réduire la quantité de données lues. Si le champ d'application est omis, la valeur par défaut est PREDICATE (c'est-à-dire la clause WHERE et JOIN-ON).

Le fait d'extraire une sous-requête scalaire vers une instruction DECLARE rend statique le prédicat d'origine et permet donc d'améliorer la planification de l'exécution. Cette optimisation introduira de nouvelles instructions SQL.
REWRITE_CTE_TO_TEMP_TABLE threshold: N Réécrit les expressions de table courantes (CTE) en tables temporaires lorsqu'il existe plus de N références à la même expression de table courante. Cela réduit la complexité des requêtes et force l'exécution unique de l'expression de table commune. Si N est omis, la valeur par défaut est 4.

Nous vous recommandons d'utiliser cette optimisation lorsque des CTE non triviales sont référencées plusieurs fois. L'introduction de tables temporaires entraîne des frais généraux qui peuvent être supérieurs aux éventuelles exécutions multiples d'une CTE à faible complexité ou à faible cardinalité. Cette optimisation introduira de nouvelles instructions SQL.
REWRITE_ZERO_SCALE_NUMERIC_AS_INTEGER bigint: N Réécrit des attributs NUMERIC/BIGNUMERIC à échelle nulle en type INT64 si la précision est comprise dans N. Si N est omis, la valeur par défaut est 18.

Nous vous recommandons d'utiliser cette optimisation lorsque vous traduisez à partir de dialectes sources qui ne comportent pas de types d'entiers. La modification des types de colonnes nécessite d'examiner toutes les utilisations en aval pour vérifier la compatibilité des types et les changements sémantiques. Par exemple, les divisions fractionnaires qui deviennent des divisions entières, ou le code qui attend des valeurs numériques.
DROP_TEMP_TABLE Ajoute des instructions DROP TABLE pour toutes les tables temporaires créées dans un script et non supprimés à la fin de celui-ci. Cela réduit la période de facturation du stockage de la table temporaire de 24 heures à la durée d'exécution du script. Cette optimisation introduira de nouvelles instructions SQL.

Nous vous recommandons d'utiliser cette optimisation lorsque les tables temporaires ne sont pas consultées pour un traitement ultérieur après la fin de l'exécution du script. Cette optimisation introduira de nouvelles instructions SQL.
REGEXP_CONTAINS_TO_LIKE Réécrit certaines catégories de modèles de correspondance REGEXP_CONTAINS en expressions LIKE.

Nous vous recommandons d'utiliser cette optimisation lorsqu'aucun autre processus, tel que le remplacement de macro, ne repose sur la conservation des littéraux de modèle d'expression régulière dans le code SQL de sortie.
ADD_DISTINCT_TO_SUBQUERY_IN_SET_COMPARISON Ajoute la clause DISTINCT aux sous-requêtes utilisées comme ensemble de valeurs pour l'opérateur [NOT] IN.

Nous vous recommandons d'utiliser cette optimisation lorsque la cardinalité (nombre distinct de valeurs) du résultat de la sous-requête est nettement inférieure au nombre de valeurs. Lorsque cette condition préalable n'est pas remplie, cette transformation peut avoir des effets négatifs sur les performances.

Créer un fichier YAML de configuration basé sur Gemini

Pour générer une sortie d'IA, le répertoire source contenant votre entrée de traduction SQL doit inclure un fichier YAML de configuration.

Conditions requises

Le fichier YAML de configuration des sorties d'IA doit porter le suffixe .ai_config.yaml. Exemple :rules_1.ai_config.yaml

Champs pris en charge

suggestion_type: SUGGESTION_TYPE
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
…
…

Vous pouvez remplacer les variables suivantes pour configurer la sortie de votre traduction par IA:

  • SUGGESTION_TYPE (facultatif): spécifiez le type de suggestion d'IA à générer. Les types de suggestions suivants sont acceptés:

    • QUERY_CUSTOMIZATION (par défaut): génère des suggestions d'IA pour le code SQL en fonction des règles de traduction spécifiées dans le fichier YAML de configuration.
    • TRANSLATION_EXPLANATION: génère un texte qui inclut un résumé de la requête GoogleSQL traduite, ainsi que les différences et les incohérences entre la requête SQL source et la requête GoogleSQL traduite.
    • CUSTOM_SUGGESTION: génère des sorties SQL ou textuelles à l'aide d'artefacts de traduction. Les utilisateurs peuvent se référer aux artefacts de traduction dans les requêtes qui incluent des espaces réservés. Le service de traduction ajoute les artefacts correspondants à la requête LLM finale envoyée à Gemini. Les artefacts de traduction suivants peuvent être inclus dans l'invite :
      • {{SOURCE_DIALECT}}: permet de faire référence au dialecte SQL source.
      • {{SOURCE_SQL}}: permet de référencer le code source SQL de la traduction.
      • {{TARGET_SQL}}: permet de faire référence à l'instruction SQL traduite par défaut.

  • TARGET (facultatif): 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 (facultatif): en langage naturel, décrivez une modification apportée au code SQL cible. La traduction SQL améliorée par Gemini évalue la requête et effectue la modification spécifiée.

  • 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 des translation_rules et des examples supplémentaires si nécessaire.

Examples

Les exemples suivants créent des fichiers YAML de configuration basés sur Gemini que vous pouvez utiliser avec vos traductions SQL.

Supprimer la fonction upper dans la requête de sortie de traduction par défaut

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

Créer plusieurs règles de traduction pour personnaliser la sortie de traduction

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.

Supprimer les commentaires SQL de la requête d'entrée de traduction

rewrite_target: SOURCE_SQL
translation_rules:
- instruction: "Remove all the sql comments in the input sql query."

Générer des explications de traduction à l'aide de la requête LLM par défaut

Cet exemple utilise les requêtes LLM par défaut fournies par le service de traduction pour générer des explications textuelles:

suggestion_type: "TRANSLATION_EXPLANATION"

Génère des explications de traduction à l'aide de vos propres requêtes en langage naturel

suggestion_type: "TRANSLATION_EXPLANATION"
instruction: "Explain the syntax differences between the source Teradata query and the translated GoogleSQL query."

Corrige l'erreur de traduction MySQL vers GoogleSQL: unsupported constraint on PRIMARY

suggestion_type: "CUSTOM_SUGGESTION"
instruction: "Add PRIMARY KEY (...) NOT ENFORCED to the target sql as a column constraint based on the source sql. Output sql without sql code block.\n\nsource sql: {{SOURCE_SQL}}\ntarget sql: {{TARGET_SQL}}"

Appliquer plusieurs configurations YAML

Lorsque vous spécifiez un fichier YAML de configuration dans une traduction SQL par lot ou en SQL interactif, vous pouvez sélectionner plusieurs fichiers YAML de configuration dans un seul job de traduction pour refléter plusieurs transformations. Si plusieurs configurations sont en conflit, une transformation peut remplacer une autre. Nous vous recommandons d'utiliser différents types de paramètres de configuration dans chaque fichier pour éviter les conflits de transformations dans le même job de traduction.

L'exemple suivant répertorie deux fichiers de configuration YAML distincts fournis pour un seul job de traduction SQL, l'un pour modifier l'attribut d'une colonne et l'autre pour définir la table comme temporaire :

change-type-example.config.yaml :

type: object_rewriter
attribute:
  -
    match: "testdb.testschema.x.a"
    type:
      target: NUMERIC(10,2)

make-temp-example.config.yaml :

type: object_rewriter
relation:
  -
    match: "testdb.testschema.x"
    temporary: true

Une traduction SQL avec ces deux fichiers YAML de configuration peut se présenter comme suit :

teradata-input.sql 
    create table x(a int);
bq-output.sql 
    CREATE TEMPORARY TABLE x
    (
      a NUMERIC(31, 2)
    )
    ;