Mapper les noms d'objet SQL pour la traduction par lot

Ce document explique comment configurer le mappage de noms pour renommer les objets SQL lors de la traduction par lot.

Présentation

Le mappage de noms vous permet d'identifier les noms d'objets SQL dans vos fichiers sources et de spécifier des noms cibles pour ces objets dans BigQuery. Vous pouvez utiliser tout ou partie des composants suivants pour configurer le mappage de noms pour un objet :

  • Une règle de mappage de noms composée des éléments suivants :
    • Les parties du nom source qui fournissent le nom complet de l'objet dans le système source.
    • Un type qui identifie le type d'objet source.
    • Les parties du nom cible qui fournissent le nom de l'objet dans BigQuery.
  • Un nom de base de données par défaut à utiliser avec tous les objets sources qui n'en spécifient pas.
  • Un nom de schéma par défaut à utiliser avec tous les objets sources qui n'en spécifient pas.

Parties de nom

Vous fournissez les valeurs des noms d'objets source et cible dans une règle de mappage de noms en combinant les parties de nom suivantes :

  • Base de données : niveau supérieur de la hiérarchie des noms. Votre plate-forme source peut utiliser un autre alternatif pour cela, par exemple projet.
  • Schéma : deuxième niveau de la hiérarchie des noms. Votre plate-forme source peut utiliser un autre terme pour cet exemple, par exemple ensemble de données.
  • Relation : troisième niveau de la hiérarchie des noms. Votre plate-forme source peut utiliser un autre terme pour cela, par exemple table.
  • Attribut : niveau le plus bas de la hiérarchie des noms. Votre plate-forme source peut utiliser un autre terme pour cela, par exemple colonne.

Types d'objet

Vous devez également spécifier le type d'objet source que vous renommez dans une règle de mappage de noms. Les types d'objets suivants sont acceptés :

  • Database : objet de premier niveau dans la hiérarchie des objets, par exemple database.schema.relation.attribute. Votre plate-forme source peut utiliser un autre terme pour cela, par exemple projet. La spécification de database comme type d'objet modifie toutes les références à la chaîne source dans les instructions LDD et LMD.
  • Schema : objet de deuxième niveau dans la hiérarchie des objets. Votre plate-forme source peut utiliser un autre terme pour cet exemple, par exemple ensemble de données. La spécification de schema comme type d'objet modifie toutes les références à la chaîne source dans les instructions LDD et LMD.
  • Relation : objet de troisième niveau dans la hiérarchie des objets. Votre plate-forme source peut utiliser un autre terme pour cela, par exemple table. La spécification de relation comme type d'objet modifie toutes les références à la chaîne source dans les instructions LDD.
  • Relation alias : alias d'un objet de troisième niveau. Par exemple, dans la requête SELECT t.field1, t.field2 FROM myTable t;, t est un alias de relation. Dans la requête SELECT field1, field2 FROM schema1.table1, table1 est également un alias de relation. La spécification de relation alias comme type d'objet crée des alias pour toutes les références à la chaîne source dans les instructions LMD. Par exemple, si tableA est spécifié comme nom cible, les exemples précédents sont traduits respectivement par SELECT tableA.field1, tableA.field2 FROM myTable AS tableA; et par SELECT tableA.field1, tableA.field2 FROM schema1.table1 AS tableA.
  • Function : procédure, par exemple create procedure db.test.function1(a int). La spécification de function comme type d'objet modifie toutes les références à la chaîne source dans les instructions LDD et LMD.
  • Attribute : objet de quatrième niveau dans la hiérarchie des objets. Votre plate-forme source peut utiliser un autre terme pour cela, par exemple colonne. La spécification de attribute comme type d'objet modifie toutes les références à la chaîne source dans les instructions LDD.
  • Attribute alias : alias d'un objet de quatrième niveau. Par exemple, dans la requête SELECT field1 FROM myTable;, field1 est un alias d'attribut. La définition de attribute alias comme type d'objet modifie toutes les références à la chaîne source dans les instructions LMD.

Parties de nom requises pour les types d'objets

Pour décrire un objet dans une règle de mappage de noms, utilisez les parties de nom identifiées pour chaque type d'objet dans le tableau suivant :

Type Nom d'objet source Nom d'objet cible
Partie de base de données Partie de nom de schéma Partie de nom de relation Partie de nom d'attribut Partie de base de données Partie de nom de schéma Partie de nom de relation Partie de nom d'attribut
Database X X
Schema X X X X
Relation X X X X X X
Function X X X X X X
Attribute X X X X X
Attribute alias X X X X X
Relation alias X X

Base de données par défaut

Si vous souhaitez ajouter un nom de projet BigQuery à tous les objets traduits, le plus simple est de spécifier un nom de base de données par défaut lorsque vous créez une tâche de traduction. Cela fonctionne pour les fichiers sources dans lesquels les noms en trois parties sont utilisés ou lorsque la dénomination en quatre parties est utilisée, mais que le nom d'objet de niveau le plus élevé n'est pas spécifié.

Par exemple, si vous spécifiez le nom de base de données par défaut myproject, une instruction source telle que SELECT * FROM database.table est traduite par SELECT * FROM myproject.database.table. Si vous avez des objets qui utilisent déjà une partie du nom de la base de données, telle que SELECT * FROM database.schema.table, vous devez utiliser une règle de mappage de noms pour renommer database.schema.table en myproject.schema.table.

Schéma par défaut

Si vous souhaitez qualifier tous les noms d'objets dans les fichiers sources qui n'utilisent pas de dénomination en quatre parties, vous pouvez indiquer un nom de base de données par défaut et un nom de schéma par défaut lorsque vous créez un job de traduction. Le nom de schéma par défaut est fourni comme premier nom de schéma dans l'option de chemin de recherche de schéma.

Par exemple, si vous spécifiez le nom de base de données par défaut myproject et le nom de schéma par défaut myschema, les instructions sources suivantes :

  • SELECT * FROM database.table
  • SELECT * FROM table1

sont traduites par :

  • SELECT * FROM myproject.database.table.
  • SELECT * FROM myproject.myschema.table1

Comportement de la règle de mappage de noms

Les sections suivantes décrivent le comportement des règles de mappage de noms.

L'héritage des règles descend dans la hiérarchie des objets

Un changement de nom qui affecte un objet de niveau supérieur affecte l'objet cible ainsi que tous ses objets enfants de la même hiérarchie.

Par exemple, si vous spécifiez la règle de mappage de noms suivante avec un type d'objet schema :

Partie de nom Source Cible
Base de données sales_db sales
Schéma cust_mgmt cms
Relation
Attribut

Lorsqu'appliqué, les parties du nom de la base de données et du schéma de tous les objets relation et attribute du schéma sales_db.cust_mgmt sont également modifiées. Par exemple, un objet relation nommé sales_db.cust_mgmt.history devient sales.cms.history.

Inversement, les changements de nom qui ciblent des objets de niveau inférieur n'affectent pas les objets de niveau supérieur ou identique dans la hiérarchie des objets.

Par exemple, si vous spécifiez la règle de mappage de noms suivante avec un type d'objet relation :

Partie de nom Source Cible
Base de données sales_db sales
Schéma cust_mgmt cms
Relation clients accounts
Attribut

Lorsqu'appliqué, aucun autre objet du niveau sales_db ou sales_db.cust_mgmt de la hiérarchie des objets ne change de nom.

La règle la plus spécifique est appliquée

Une seule règle de mappage de nom est appliquée à un objet. Si plusieurs règles peuvent affecter un seul objet, la règle qui affecte la partie du nom du niveau le plus bas est appliquée. Par exemple, si une règle de mappage de noms de type database et une règle de mappage de noms de type schema peuvent toutes deux affecter le nom d'un objet relation, la règle mappage de noms de type schema est appliquée.

Utiliser une combinaison unique de valeurs de type et de source

Vous ne pouvez pas spécifier plusieurs règles de mappage de noms avec les mêmes valeurs de type et de source. Par exemple, vous ne pouvez pas spécifier les deux règles de mappage de noms suivantes :

Règle 1, type attribute Règle 2, type attribute
Partie de nom Source Cible Source Cible
Base de données project project
Schéma dataset1 dataset1
Relation table1 table1
Attribut lname last_name lname lastname

Créer des règles de mappage de noms attribute et attribute alias correspondantes

Lorsque vous utilisez une règle de mappage de noms de type attribute pour modifier un nom d'attribut dans les instructions LDD, vous devez créer une règle de mappage de noms attribute alias pour modifier également le nom de cet attribut dans les instructions LMD.

Les modifications de nom ne se répercutent pas en cascade

Les modifications de nom ne se répercutent pas entre les règles de nom. Par exemple, si vous avez créé une règle de mappage de noms qui renomme database1 en project1 et une autre qui renomme project1 en project2, le traducteur ne mappe pas database1 à project2.

Gérer les objets sources qui ne comportent pas de nom en quatre parties

Certains systèmes sources, tels que Teradata, utilisent trois parties de nom pour qualifier complètement les noms d'objet. De nombreux systèmes sources vous permettent également d'utiliser des noms partiellement qualifiés dans leurs dialectes SQL, par exemple en utilisant database1.schema1.table1, schema1.table1 et table1 pour faire référence au même objet dans différents contextes. Si vos fichiers source contiennent des objets qui n'utilisent pas de noms d'objet en quatre parties, vous pouvez utiliser un mappage de noms en combinaison avec la spécification d'un nom de base de données par défaut et d'un nom de schéma par défaut pour obtenir le mappage de noms souhaité.

Pour obtenir des exemples d'utilisation de règles de mappage de noms avec un nom de base de données par défaut ou un nom de schéma par défaut, consultez la section Modifier la partie du nom de base de données pour les objets ayant différents niveaux de qualification de nom et Modifier un nom d'objet de relation partiellement qualifié.

Exemples de mappage de noms

Utilisez les exemples de cette section pour découvrir comment fonctionnent les règles de mappage de noms pour les cas d'utilisation courants.

Modifier la partie du nom de base de données pour les objets complets

Dans l'exemple suivant, la partie du nom de base de données td_project est renommée bq_project pour tous les objets database, schema, relation et function dont les noms sont complets.

Parties de nom source et cible

Partie de nom Source Cible
Base de données td_project bq_project
Schéma
Relation
Attribut

Type

  • database

Exemple d'entrée

  • SELECT * FROM td_project.schema.table;
  • SELECT * FROM td_project.schema1.table1;

Exemple de résultat :

  • SELECT * FROM bq_project.schema.table;
  • SELECT * FROM bq_project.schema1.table1

Modifier la partie du nom de base de données pour les objets ayant différents niveaux de qualification de nom

Dans l'exemple suivant, la partie de nom de base de données project est renommée bq_project pour tous les types d'objets, et bq_project est ajouté comme partie du nom de base de données pour les objets qui n'en spécifient pas.

Pour ce faire, vous devez spécifier une valeur de base de données par défaut lors de la configuration de la tâche de traduction, en plus des règles de mappage de noms. Pour plus d'informations sur la spécification d'un nom de base de données par défaut, consultez la section Envoyer une tâche de traduction.

Valeur par défaut de la base de données

  • project

Parties de nom source et cible

Partie de nom Source Cible
Base de données project bq_project
Schéma
Relation
Attribut

Type

  • database

Exemple d'entrée

  • SELECT * FROM project.schema.table;
  • SELECT * FROM schema1.table1;

Exemple de résultat :

  • SELECT * FROM bq_project.schema.table;
  • SELECT * FROM bq_project.schema1.table1

Modifier la partie de nom de la base de données et la partie de nom du schéma pour les objets complets

L'exemple suivant remplace la partie du nom de base de données warehouse1 par myproject, et également la partie du nom de schéma database1 par mydataset.

Vous pouvez également modifier les parties d'un nom d'objet relation de la même manière, en utilisant un type relation et en spécifiant les valeurs source et cible pour la partie de nom de relation.

Parties de nom source et cible

Partie de nom Source Cible
Base de données warehouse1 myproject
Schéma database1 mydataset
Relation
Attribut

Type

  • schema

Exemple d'entrée

  • SELECT * FROM warehouse1.database1.table1;
  • SELECT * FROM database2.table2;

Exemple de résultat :

  • SELECT * FROM myproject.mydataset.table1;
  • SELECT * FROM __DEFAULT_DATABASE__.database2.table2;

Modifier un nom d'objet relation complet

L'exemple suivant renomme mydb.myschema.mytable en mydb.myschema.table1.

Parties de nom source et cible

Partie de nom Source Cible
Base de données mydb mydb
Schéma myschema myschema
Relation mytable table1
Attribut

Type

  • relation

Exemple d'entrée

  • CREATE table mydb.myschema.mytable(id int, name varchar(64));

Exemple de résultat :

  • CREATE table mydb.myschema.table1(id integer, name string(64));

Modifier un nom d'objet relation partiellement qualifié

L'exemple suivant renomme myschema.mytable en mydb.myschema.table1.

Valeur par défaut de la base de données

  • mydb

Parties de nom source et cible

Partie de nom Source Cible
Base de données mydb mydb
Schéma myschema myschema
Relation mytable table1
Attribut

Type

  • relation

Exemple d'entrée

  • CREATE table myschema.mytable(id int, name varchar(64));

Exemple de résultat :

  • CREATE table mydb.myschema.table1(id integer, name string(64));

Modifier un nom d'objet relation alias

L'exemple suivant renomme toutes les instances de la table d'objets relation alias en t.

Parties de nom source et cible

Partie de nom Source Cible
Base de données
Schéma
Relation table t
Attribut

Type

  • relation alias

Exemple d'entrée

  • SELECT table.id, table.name FROM mydb.myschema.mytable table

Exemple de résultat :

  • SELECT t.id, t.name FROM mydb.myschema.mytable AS t

Modifier un nom d'objet function

L'exemple suivant renomme mydb.myschema.myfunction en mydb.myschema.function1.

Parties de nom source et cible

Partie de nom Source Cible
Base de données mydb mydb
Schéma myschema myschema
Relation myprocedure procedure1
Attribut

Type

  • function

Exemple d'entrée

  • CREATE PROCEDURE mydb.myschema.myprocedure(a int) BEGIN declare i int; SET i = a + 1; END;
  • CALL mydb.myschema.myprocedure(7)

Exemple de résultat :

  • CREATE PROCEDURE mydb.myschema.procedure1(a int) BEGIN declare i int; SET i = a + 1; END;
  • CALL mydb.myschema.procedure1(7);

Modifier un nom d'objet attribute

L'exemple suivant renomme mydb.myschema.mytable.myfield en mydb.myschema.mytable.field1. Comme les objets attribute se trouvent au niveau le plus bas de la hiérarchie des objets, ce mappage de noms ne modifie pas le nom des autres objets.

Parties de nom source et cible

Partie de nom Source Cible
Base de données mydb
Schéma myschema
Relation mytable
Attribut myfield field1

Type

  • attribute

Exemple d'entrée

  • CREATE table mydb.myschema.mytable(myfield int, name varchar(64), revenue int);

Exemple de résultat :

  • CREATE table mydb.myschema.mytable(field1 int, name varchar(64), revenue int);

Modifier un nom d'objet attribute alias

L'exemple suivant renomme mydb.myschema.mytable.myfield en mydb.myschema.mytable.field1. Comme les objets attribute alias se trouvent au niveau le plus bas de la hiérarchie des objets, ce mappage de noms ne modifie pas le nom des autres objets.

Parties de nom source et cible

Partie de nom Source Cible
Base de données mydb
Schéma myschema
Relation mytable
Attribut myfield field1

Type

  • attribute alias

Exemple d'entrée

  • SELECT myfield, name FROM mydb.myschema.mytable;

Exemple de résultat :

  • SELECT field1, name FROM mydb.myschema.mytable;

Format des fichiers JSON

Si vous choisissez de spécifier des règles de mappage de noms à l'aide d'un fichier JSON plutôt que de la console Google Cloud, le fichier JSON doit respecter le format suivant :

{
  "name_map": [
    {
      "source": {
        "type": "string",
        "database": "string",
        "schema": "string",
        "relation": "string",
        "attribute": "string"
      },
      "target": {
        "database": "string",
        "schema": "string",
        "relation": "string",
        "attribute": "string"
      }
    }
  ]
}

La taille du fichier doit être inférieure à 5 Mo.

Pour en savoir plus sur la spécification des règles de mappage de noms pour une tâche de traduction, consultez la page Envoyer une tâche de traduction.

Exemples JSON

Les exemples suivants montrent comment spécifier des règles de mappage de noms à l'aide de fichiers JSON.

Exemple 1

Les règles de mappage de noms dans cet exemple modifient le nom d'objet suivant :

  • Renommer les instances de l'objet relation project.dataset2.table2 en bq_project.bq_dataset2.bq_table2.
  • Renommer toutes les instances de l'objet database project en bq_project. Par exemple, project.mydataset.table2 devient bq_project.mydataset.table2 et CREATE DATASET project.mydataset devient CREATE DATASET bq_project.mydataset.
{
  "name_map": [{
    "source": {
      "type": "RELATION",
      "database": "project",
      "schema": "dataset2",
      "relation": "table2"
    },
    "target": {
      "database": "bq_project",
      "schema": "bq_dataset2",
      "relation": "bq_table2"
    }
  }, {
    "source": {
      "type": "DATABASE",
      "database": "project"
    },
    "target": {
      "database": "bq_project"
    }
  }]
}

Exemple 2

Les règles de mappage de noms dans cet exemple modifient le nom d'objet suivant :

  • Remplacer les instances de l'objet attribute project.dataset2.table2.field1 par bq_project.bq_dataset2.bq_table2.bq_field dans les instructions LDD et LMD.
{
  "name_map": [{
    "source": {
      "type": "ATTRIBUTE",
      "database": "project",
      "schema": "dataset2",
      "relation": "table2",
      "attribute": "field1"
    },
    "target": {
      "database": "bq_project",
      "schema": "bq_dataset2",
      "relation": "bq_table2",
      "attribute": "bq_field"
    }
  }, {
    "source": {
      "type": "ATTRIBUTE_ALIAS",
      "database": "project",
      "schema": "dataset2",
      "relation": "table2",
      "attribute": "field1"
    },
    "target": {
      "database": "bq_project",
      "schema": "bq_dataset2",
      "relation": "bq_table2",
      "attribute": "bq_field"
    }
  }]
}