Mappa i nomi degli oggetti SQL per la traduzione batch

Questo documento descrive come configurare la mappatura dei nomi per rinominare gli oggetti SQL durante la traduzione batch.

Panoramica

La mappatura dei nomi ti consente di identificare i nomi degli oggetti SQL nei file di origine e di specificare i nomi di destinazione per questi oggetti in BigQuery. Puoi utilizzare alcuni o tutti i seguenti componenti per configurare la mappatura dei nomi di un oggetto:

• Una regola di mappatura dei nomi, composta da:
  • Parti del nome della sorgente che forniscono il nome completo dell'oggetto nel sistema di origine.
  • Un type che identifica il tipo di oggetto di origine.
  • Parti del nome target che forniscono il nome dell'oggetto in BigQuery.
• Un nome di database predefinito da utilizzare con gli oggetti di origine che non ne specificano uno.
• Il nome di uno schema predefinito da utilizzare con gli oggetti di origine che non ne specificano uno.

Assegnare un nome alle parti

Fornisci i valori per i nomi degli oggetti di origine e di destinazione in una regola di mappatura dei nomi utilizzando una combinazione delle seguenti parti del nome:

• Database: il livello più alto della gerarchia dei nomi. La piattaforma di origine potrebbe utilizzare un termine alternativo, ad esempio project.
• Schema: il secondo livello della gerarchia dei nomi. La piattaforma di origine potrebbe utilizzare un termine alternativo, ad esempio set di dati.
• Relazione: il terzo livello della gerarchia dei nomi. La piattaforma di origine potrebbe utilizzare un termine alternativo, ad esempio table.
• Attributo: il livello più basso della gerarchia dei nomi. La piattaforma di origine potrebbe utilizzare un termine alternativo, ad esempio colonna.

Tipi di oggetti

Devi anche specificare il tipo di oggetto di origine da rinominare in una regola di mappatura dei nomi. Sono supportati i seguenti tipi di oggetti:

• Database: un oggetto di primo livello nella gerarchia degli oggetti, ad esempio database.schema.relation.attribute. La piattaforma di origine potrebbe utilizzare un termine alternativo, ad esempio project. Se specifichi database come tipo di oggetto, tutti i riferimenti alla stringa di origine vengono modificati sia negli enunciati DDL sia in quelli DML.
• Schema: un oggetto di secondo livello nella gerarchia degli oggetti. La piattaforma di origine potrebbe utilizzare un termine alternativo, ad esempio set di dati. Se specifichi schema come tipo di oggetto, vengono modificati tutti i riferimenti alla stringa di origine sia negli statement DDL sia in quelli DML.
• Relation: un oggetto di terzo livello nella gerarchia degli oggetti. La piattaforma di origine potrebbe utilizzare un termine alternativo, ad esempio table. Se specifichi relation come tipo di oggetto, vengono modificati tutti i riferimenti alla stringa di origine negli enunciati DDL.
• Relation alias: un alias per un oggetto di terzo livello. Ad esempio, nella query SELECT t.field1, t.field2 FROM myTable t;, t è un alias di relazione. Nella query SELECT field1, field2 FROM schema1.table1, table1 è anche un alias relazione. Se specifichi relation alias come tipo di oggetto, vengono creati alias per tutti i riferimenti alla stringa di origine negli enunciati DML. Ad esempio, se viene specificato tableA come nome target, gli esempi precedenti vengono tradotti rispettivamente come SELECT tableA.field1, tableA.field2 FROM myTable AS tableA; e SELECT tableA.field1, tableA.field2 FROM schema1.table1 AS tableA.
• Function: una procedura, ad esempiocreate procedure db.test.function1(a int). Se specifichi function come tipo di oggetto, vengono modificati tutti i riferimenti alla stringa di origine sia negli statement DDL sia in quelli DML.
• Attribute: un oggetto di quarto livello nella gerarchia degli oggetti. La piattaforma di origine potrebbe utilizzare un termine alternativo, ad esempio colonna. Se specifichi attribute come tipo di oggetto, vengono modificati tutti i riferimenti alla stringa di origine negli enunciati DDL.
• Attribute alias: un alias per un oggetto di quarto livello. Ad esempio, nella query SELECT field1 FROM myTable;, field1 è un alias dell'attributo. Se specifichi attribute alias come tipo di oggetto, vengono modificati tutti i riferimenti alla stringa di origine negli enunciati DML.

Parti del nome obbligatorie per i tipi di oggetti

Per descrivere un oggetto in una regola di mappatura dei nomi, utilizza le parti del nome identificate per ogni tipo di oggetto nella tabella seguente:

Database predefinito

Se vuoi aggiungere un nome di progetto BigQuery a tutti gli oggetti tradotti, la cosa più semplice da fare è specificare un nome di database predefinito quando crei un job di traduzione. Questo funziona per i file di origine in cui viene utilizzato il nome in tre parti o in cui viene utilizzato il nome in quattro parti, ma il nome dell'oggetto di primo livello non è specificato.

Ad esempio, se specifichi il nome del database predefinito myproject, un statement di origine come SELECT * FROM database.table viene tradotto in SELECT * FROM myproject.database.table. Se hai oggetti che utilizzano già una parte del nome del database, ad esempio SELECT * FROM database.schema.table, devi utilizzare una regola di mappatura dei nomi per rinominare database.schema.table in myproject.schema.table.

Schema predefinito

Se vuoi specificare completamente tutti i nomi degli oggetti nei file di origine che non utilizzano la denominazione in quattro parti, puoi fornire sia un nome del database predefinito sia un nome dello schema predefinito quando crei un job di traduzione. Il nome dello schema predefinito viene fornito come primo nome dello schema nell'opzione del percorso di ricerca dello schema.

Ad esempio, se specifichi il nome predefinito del database myproject e il nome predefinito dello schema myschema, le seguenti istruzioni di origine:

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

Vengono tradotti in:

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

Comportamento della regola di mappatura dei nomi

Le sezioni seguenti descrivono il comportamento delle regole di mappatura dei nomi.

L'eredità delle regole avviene lungo la gerarchia degli oggetti

Una modifica del nome che interessa un oggetto di livello superiore influisce sull'oggetto di destinazione e anche su tutti i suoi oggetti secondari nella stessa gerarchia.

Ad esempio, se specifichi la seguente regola di mappatura dei nomi con un tipo di oggetto schema:

Quando viene applicata, vengono modificate anche le parti del nome del database e dello schema di tutti gli oggetti relation e attribute nello schema sales_db.cust_mgmt. Ad esempio, un oggetto relation denominato sales_db.cust_mgmt.history diventa sales.cms.history.

Al contrario, le modifiche ai nomi che hanno come target oggetti di livello inferiore non influiscono sugli oggetti di livello superiore o dello stesso livello nella gerarchia degli oggetti.

Ad esempio, se specifichi la seguente regola di mappatura dei nomi con un tipo di oggetto relation:

Quando viene applicato, il nome di nessun altro oggetto a livello sales_db o sales_db.cust_mgmt della gerarchia degli oggetti viene modificato.

Viene applicata la regola più specifica

A un oggetto viene applicata una sola regola di mappatura dei nomi. Se più regole possono colpire un singolo oggetto, viene applicata la regola che interessa la parte del nome di livello più basso. Ad esempio, se una regola di mappatura del nome del tipo database e una regola di mappatura del nome del tipo schema possono influire sul nome di un oggetto relation, viene applicata la regola di mappatura del nome del tipo schema.

Utilizza una combinazione univoca di valori di tipo e di origine

Non puoi specificare più di una regola di mappatura dei nomi con gli stessi valori di tipo e origine. Ad esempio, non puoi specificare entrambe le seguenti regole di mappatura dei nomi:

Crea regole di mappatura dei nomi attribute e attribute alias corrispondenti

Quando utilizzi una regola di mappatura dei nomi di tipo attribute per modificare il nome di un attributo nelle istruzioni DDL, devi creare una regola di mappatura dei nomi attribute alias per modificare il nome dell'attributo anche nelle istruzioni DML.

Le modifiche ai nomi non si applicano in modo ricorsivo

Le modifiche ai nomi non vengono applicate alle regole dei nomi. Ad esempio, se hai creato una regola di mappatura dei nomi che rinomina database1 in project1 e un'altra che rinomina project1 in project2, il traduttore non mappa database1 in project2.

Gestire gli oggetti di origine che non hanno nomi in quattro parti

Alcuni sistemi di origine, come Teradata, utilizzano tre parti del nome per specificare completamente i nomi degli oggetti. Molti sistemi di origine consentono inoltre di utilizzare nomi parzialmente qualificati nei loro dialetti SQL, ad esempio utilizzando database1.schema1.table1, schema1.table1 e table1 per fare riferimento allo stesso oggetto in contesti diversi. Se i file di origine contengono oggetti che non utilizzano nomi di oggetti in quattro parti, puoi utilizzare la mappatura dei nomi in combinazione con la specifica di un nome del database predefinito e di un nome dello schema predefinito per ottenere la mappatura dei nomi che preferisci.

Per esempi di utilizzo delle regole di mappatura dei nomi con un nome del database o dello schema predefinito, consulta Modificare la parte del nome del database per gli oggetti con diversi livelli di completamento del nome e Modificare il nome di un oggetto relazione parzialmente qualificato.

Esempi di mappatura dei nomi

Utilizza gli esempi in questa sezione per capire come funzionano le regole di mappatura dei nomi per i casi d'uso comuni.

Modificare la parte del nome del database per gli oggetti completamente qualificati

L'esempio seguente rinomina la parte del nome del database da td_project a bq_project per tutti gli oggetti database, schema, relation e function che hanno nomi completi.

Parti del nome di origine e di destinazione

Tipo

• database

Input di esempio

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

Output di esempio

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

Modificare la parte del nome del database per gli oggetti con diversi livelli di completamento del nome

L'esempio seguente rinomina la parte del nome del database project in bq_project per tutti i tipi di oggetti e aggiunge bq_project come parte del nome del database per gli oggetti che non ne specificano uno.

Per farlo, devi specificare un valore predefinito del database durante la configurazione del job di traduzione, oltre a specificare le regole di mappatura dei nomi. Per ulteriori informazioni su come specificare un nome di database predefinito, consulta Inviare un job di traduzione.

Valore predefinito del database

• project

Parti del nome di origine e di destinazione

Tipo

• database

Input di esempio

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

Output di esempio

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

Modificare la parte del nome del database e la parte del nome dello schema per gli oggetti completamente qualificati

Nell'esempio seguente la parte del nome del database warehouse1 viene modificata in myproject e anche la parte del nome dello schema database1 viene modificata in mydataset.

Puoi anche modificare le parti del nome di un oggetto relation allo stesso modo, utilizzando un tipo relation e specificando i valori di origine e destinazione per la parte del nome della relazione.

Parti del nome di origine e di destinazione

Tipo

• schema

Input di esempio

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

Output di esempio

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

Modificare un nome completo dell'oggetto relation

Nell'esempio seguente mydb.myschema.mytable viene rinominato in mydb.myschema.table1.

Parti del nome di origine e di destinazione

Tipo

• relation

Input di esempio

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

Output di esempio

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

Modificare un nome di oggetto relation parzialmente qualificato

Nell'esempio seguente myschema.mytable viene rinominato in mydb.myschema.table1.

Valore predefinito del database

• mydb

Parti del nome di origine e di destinazione

Tipo

• relation

Input di esempio

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

Output di esempio

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

Modificare il nome di un oggetto relation alias

L'esempio seguente rinomina tutte le istanze dell'oggetto relation alias table in t.

Parti del nome di origine e di destinazione

Tipo

• relation alias

Input di esempio

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

Output di esempio

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

Modificare il nome di un oggetto function

Nell'esempio seguente mydb.myschema.myfunction viene rinominato in mydb.myschema.function1.

Parti del nome di origine e di destinazione

Tipo

• function

Input di esempio

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

Output di esempio

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

Modificare il nome di un oggetto attribute

Nell'esempio seguente mydb.myschema.mytable.myfield viene rinominato in mydb.myschema.mytable.field1. Poiché gli oggetti attribute si trovano al livello più basso della gerarchia degli oggetti, questa mappatura dei nomi non modifica il nome di nessun altro oggetto.

Parti del nome di origine e di destinazione

Tipo

• attribute

Input di esempio

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

Output di esempio

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

Modificare il nome di un oggetto attribute alias

Nell'esempio seguente mydb.myschema.mytable.myfield viene rinominato in mydb.myschema.mytable.field1. Poiché gli oggetti attribute alias si trovano al livello più basso della gerarchia degli oggetti, questa mappatura dei nomi non modifica il nome di nessun altro oggetto.

Parti del nome di origine e di destinazione

Tipo

• attribute alias

Input di esempio

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

Output di esempio

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

Formato file JSON

Se scegli di specificare le regole di mappatura dei nomi utilizzando un file JSON anziché la console Google Cloud, il file JSON deve avere il seguente formato:

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

Le dimensioni del file devono essere inferiori a 5 MB.

Per ulteriori informazioni su come specificare le regole di mappatura dei nomi per un job di traduzione, consulta Inviare un job di traduzione.

Esempi di JSON

Gli esempi riportati di seguito mostrano come specificare le regole di mappatura dei nomi utilizzando i file JSON.

Esempio 1

Le regole di mappatura dei nomi in questo esempio apportano le seguenti modifiche ai nomi degli oggetti:

• Rinomina le istanze dell'oggetto project.dataset2.table2 relation in bq_project.bq_dataset2.bq_table2.
• Rinomina tutte le istanze dell'oggetto project database in bq_project. Ad esempio, project.mydataset.table2 diventa bq_project.mydataset.table2 e CREATE DATASET project.mydataset diventa 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"
    }
  }]
}

Esempio 2

Le regole di mappatura dei nomi in questo esempio apportano le seguenti modifiche ai nomi degli oggetti:

• Rinomina le istanze dell'oggetto project.dataset2.table2.field1 attribute in bq_project.bq_dataset2.bq_table2.bq_field sia nelle istruzioni DDL sia in quelle DML.

{
  "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"
    }
  }]
}