Asigna nombres de objetos SQL para la traducción por lotes

Vista previa

Este producto está sujeto a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones específicas del Servicio. Los productos de la fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Nota: La asignación de nombres de objetos con JSON solo es compatible con la API de lotes heredada. Si usas la API de BigQuery Migration o inicias trabajos por lotes desde la consola de Google Cloud, usa asignación de nombres de objetos basada en YAML en su lugar.

En este documento, se describe cómo configurar la asignación de nombres para cambiar el nombre de los objetos SQL durante la traducción por lotes.

Descripción general

La asignación de nombres te permite identificar los nombres de los objetos SQL en tus archivos de origen y especificar nombres de destino para esos objetos en BigQuery. Puedes usar algunos de los siguientes componentes o todos ellos a fin de configurar la asignación de nombres para un objeto:

• Una regla de asignación de nombres, que consta de los siguientes elementos:
  • Partes del nombre de origen que proporcionan el nombre completamente calificado del objeto en el sistema de origen.
  • Un tipo que identifica el tipo de objeto de origen.
  • Partes del nombre de destino que proporcionan el nombre del objeto en BigQuery.
• Un nombre de base de datos predeterminada que se usará con objetos de origen que no especifiquen una.
• Un nombre de esquema predeterminado que se usará con cualquier objeto de origen que no especifique uno.

Partes del nombre

Debes proporcionar los valores para los nombres de los objetos de origen y de destino en una regla de asignación de nombres mediante una combinación de las siguientes partes del nombre:

• Base de datos: El nivel superior de la jerarquía de nombres. Tu plataforma de origen puede usar un término alternativo para esto, por ejemplo, proyecto.
• Esquema: El segundo nivel de la jerarquía de nombres. Tu plataforma de origen puede usar un término alternativo para esto, por ejemplo, conjunto de datos.
• Relación: El tercer nivel de la jerarquía de nombres. Tu plataforma de origen puede usar un término alternativo para esto, por ejemplo, tabla.
• Atributo: El nivel más bajo de la jerarquía de nombres. Tu plataforma de origen puede usar un término alternativo para esto, por ejemplo, columna.

Tipos de objetos

También debes especificar el tipo de objeto de origen al que deseas cambiarle el nombre en una regla de asignación de nombres. Se admiten los siguientes tipos de objetos:

• Database: Un objeto de nivel superior en la jerarquía de objetos, por ejemplo, database.schema.relation.attribute Tu plataforma de origen puede usar un término alternativo para esto, por ejemplo, proyecto. Especificar database como el tipo de objeto cambia todas las referencias a la string de origen en las declaraciones DDL y DML.
• Schema: Un objeto de segundo nivel en la jerarquía de objetos. Tu plataforma de origen puede usar un término alternativo para esto, por ejemplo, conjunto de datos. Especificar schema como el tipo de objeto cambia todas las referencias a la string de origen en las declaraciones DDL y DML.
• Relation: Un objeto de tercer nivel en la jerarquía de objetos. Tu plataforma de origen puede usar un término alternativo para esto, por ejemplo, tabla. Si especificas relation como el tipo de objeto, se cambian todas las referencias a la string de origen en las declaraciones DDL.
• Relation alias: Es un alias para un objeto de tercer nivel. Por ejemplo, en la consulta SELECT t.field1, t.field2 FROM myTable t;, t es un alias de relación. En la consulta SELECT field1, field2 FROM schema1.table1, table1 también es un alias de relación. Especificar relation alias como el tipo de objeto crea alias para todas las referencias a la string de origen en las declaraciones DML. Por ejemplo, si tableA se especifica como el nombre de destino, los ejemplos anteriores se traducen como SELECT tableA.field1, tableA.field2 FROM myTable AS tableA; y SELECT tableA.field1, tableA.field2 FROM schema1.table1 AS tableA, respectivamente.
• Function: Un procedimiento, por ejemplo, create procedure db.test.function1(a int). Especificar function como el tipo de objeto cambia todas las referencias a la string de origen en las declaraciones DDL y DML.
• Attribute: Un objeto de cuarto nivel en la jerarquía de objetos. Tu plataforma de origen puede usar un término alternativo para esto, por ejemplo, columna. Si especificas attribute como el tipo de objeto, se cambian todas las referencias a la string de origen en las declaraciones DDL.
• Attribute alias: Es un alias para un objeto de cuarto nivel. Por ejemplo, en la consulta SELECT field1 FROM myTable;, field1 es un alias de atributo. Si especificas attribute alias como el tipo de objeto, se cambian todas las referencias a la string de origen en las declaraciones DML.

Partes del nombre obligatorias para los tipos de objetos

Si deseas describir un objeto en una regla de asignación de nombres, usa las partes de nombre identificadas para cada tipo de objeto en la siguiente tabla:

Tipo	Nombre del objeto de origen				Nombre del objeto de destino
	Parte del nombre de la base de datos	Parte del nombre del esquema	Parte del nombre de la relación	Parte del nombre del atributo	Parte del nombre de la base de datos	Parte del nombre del esquema	Parte del nombre de la relación	Parte del nombre del atributo
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 datos predeterminada

Si deseas agregar un nombre de proyecto de BigQuery a todos los objetos traducidos, lo más sencillo es especificar un nombre de base de datos predeterminada cuando crees un trabajo de traducción. Esto funciona para archivos de origen en los que se usa el nombre de tres partes o en los que se usa el nombre de cuatro partes, pero no se especifica el nombre del objeto de nivel más alto.

Por ejemplo, si especificas el nombre de base de datos predeterminada myproject, una declaración de origen como SELECT * FROM database.table se traducirá a SELECT * FROM myproject.database.table. Si tienes objetos que ya usan una parte de nombre de base de datos, como SELECT * FROM database.schema.table, debes usar una regla de asignación de nombres para cambiar el nombre de database.schema.table a myproject.schema.table.

Esquema predeterminado

Si deseas calificar completamente todos los nombres de objetos en los archivos de origen que no usan nombres de cuatro partes, puedes proporcionar un nombre de base de datos predeterminada y un nombre de esquema predeterminado cuando crees un trabajo de traducción. El nombre de esquema predeterminado se proporciona como el primer nombre de esquema en la opción de ruta de búsqueda del esquema.

Por ejemplo, si especificas el nombre de base de datos predeterminada myproject y el nombre de esquema predeterminado myschema, entonces las siguientes declaraciones de origen:

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

Se traducen a:

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

Comportamiento de las reglas de asignación de nombres

En las siguientes secciones, se describe cómo se comportan las reglas de asignación de nombres.

La herencia de reglas fluye hacia abajo en la jerarquía de objetos

Un cambio de nombre que afecta a un objeto de nivel superior afecta al objeto de destino y, también, a todos sus objetos secundarios en la misma jerarquía.

Por ejemplo, si especificas la siguiente regla de asignación de nombres con un tipo de objeto schema:

Parte de nombre	Origen	Target
Base de datos	sales_db	sales
Esquema	cust_mgmt	cms
Relación
Atributo

Cuando se aplica, también se cambian las partes de nombre de la base de datos y del esquema de todos los objetos relation y attribute del esquema sales_db.cust_mgmt. Por ejemplo, un objeto relation llamado sales_db.cust_mgmt.history se convierte en sales.cms.history.

Por el contrario, los cambios de nombre destinados a objetos de nivel inferior no afectan los objetos de nivel superior o igual en la jerarquía de objetos.

Por ejemplo, si especificas la siguiente regla de asignación de nombres con un tipo de objeto relation:

Parte de nombre	Origen	Target
Base de datos	sales_db	sales
Esquema	cust_mgmt	cms
Relación	clients	accounts
Atributo

Cuando se aplica, no se cambia el nombre de ningún otro objeto en el nivel de sales_db o sales_db.cust_mgmt de la jerarquía de objetos.

Se aplica la regla más específica

Solo se aplica una regla de asignación de nombres a un objeto. Si varias reglas pueden afectar a un solo objeto, se aplica la regla que afecta la parte del nombre del nivel más bajo. Por ejemplo, si una regla de asignación de nombres de tipo database y una regla de asignación de nombres de tipo schema podrían afectar el nombre de un objeto relation, se aplica la regla de asignación de nombres de tipo schema.

Usa una combinación única de valores de tipo y origen

No puedes especificar más de una regla de asignación de nombres con los mismos valores de tipo y origen. Por ejemplo, no puedes especificar las siguientes dos reglas de asignación de nombres:

	Regla 1, tipo attribute		Regla 2, tipo attribute
Parte de nombre	Origen	Target	Origen	Target
Base de datos	project		project
Esquema	dataset1		dataset1
Relación	table1		table1
Atributo	lname	last_name	lname	lastname

Crea reglas de asignación de nombres attribute y attribute alias que coincidan

Cuando usas una regla de asignación de nombres de tipo attribute para cambiar el nombre de un atributo en las declaraciones DDL, debes crear una regla de asignación de nombres attribute alias a fin de cambiar también el nombre de ese atributo en las declaraciones DML.

Los cambios de nombre no se aplican en cascada

Los cambios de nombre no se aplican en cascada a las reglas de nombres. Por ejemplo, si creaste una regla de asignación de nombres que cambia el nombre de database1 a project1 y otra que cambia el nombre de project1 a project2, el traductor no asigna database1 a project2.

Maneja los objetos de origen que no tienen nombres de cuatro partes

Algunos sistemas de origen, como Teradata, usan tres partes de nombre para calificar por completo los nombres de objetos. Muchos sistemas de origen también te permiten usar nombres parcialmente calificados en sus dialectos de SQL, por ejemplo, usar database1.schema1.table1, schema1.table1 y table1 para hacer referencia al mismo objeto. diferentes contextos. Si tus archivos de origen contienen objetos que no usan nombres de objetos de cuatro partes, puedes usar la asignación de nombres junto con la especificación de un nombre de base de datos predeterminada y un nombre de esquema predeterminado para lograr la asignación de nombre que desees.

Para ver ejemplos de cómo usar reglas de asignación de nombres con un nombre de base de datos predeterminada o un nombre de esquema predeterminado, consulta Cambia la parte del nombre de la base de datos para objetos con diferentes niveles de finalización de nombre y Cambia un nombre de objeto de relación parcialmente calificado.

Ejemplos de asignación de nombres

Usa los ejemplos de esta sección a fin de ver cómo funcionan las reglas de asignación de nombres para los casos de uso comunes.

Cambia la parte del nombre de la base de datos para objetos completamente calificados

En el siguiente ejemplo, se cambia la parte del nombre de la base de datos de td_project a bq_project para todos los objetos database, schema, relation y function que tienen nombres completamente calificados.

Partes de nombre de origen y de destino

Parte de nombre	Origen	Target
Base de datos	td_project	bq_project
Esquema
Relación
Atributo

Tipo

• database

Entrada de ejemplo

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

Resultado de ejemplo

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

Cambia la parte del nombre de la base de datos para objetos con diferentes niveles de finalización de nombre

En el siguiente ejemplo, se cambia la parte del nombre de la base de datos de project a bq_project para todos los tipos de objetos y también se agrega bq_project como la parte del nombre de la base de datos para los objetos que no especifican una.

Para hacerlo, debes especificar un valor de base de datos predeterminada cuando configuras el trabajo de traducción, además de especificar reglas de asignación de nombres. Para obtener más información sobre cómo especificar un nombre de base de datos predeterminado, consulta Envía un trabajo de traducción.

Valor de base de datos predeterminada

• project

Partes de nombre de origen y de destino

Parte de nombre	Origen	Target
Base de datos	project	bq_project
Esquema
Relación
Atributo

Tipo

• database

Entrada de ejemplo

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

Resultado de ejemplo

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

Cambia la parte de nombre de la base de datos y la parte de nombre del esquema para objetos completamente calificados

En el siguiente ejemplo, se cambia la parte del nombre de la base de datos de warehouse1 a myproject y también la parte del nombre del esquema de database1 a mydataset.

También puedes cambiar las partes de un nombre de objeto relation de la misma manera, si usas un tipo relation y especificas valores de origen y destino para la parte de nombre de la relación.

Partes de nombre de origen y de destino

Parte de nombre	Origen	Target
Base de datos	warehouse1	myproject
Esquema	database1	mydataset
Relación
Atributo

Tipo

• schema

Entrada de ejemplo

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

Resultado de ejemplo

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

Cambia un nombre de objeto relation completamente calificado

En el siguiente ejemplo, se cambia el nombre de mydb.myschema.mytable a mydb.myschema.table1.

Partes de nombre de origen y de destino

Parte de nombre	Origen	Target
Base de datos	mydb	mydb
Esquema	myschema	myschema
Relación	mytable	table1
Atributo

Tipo

• relation

Entrada de ejemplo

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

Resultado de ejemplo

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

Cambia un nombre de objeto relation calificado parcialmente

En el siguiente ejemplo, se cambia el nombre de myschema.mytable a mydb.myschema.table1.

Valor de base de datos predeterminada

• mydb

Partes de nombre de origen y de destino

Parte de nombre	Origen	Target
Base de datos	mydb	mydb
Esquema	myschema	myschema
Relación	mytable	table1
Atributo

Tipo

• relation

Entrada de ejemplo

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

Resultado de ejemplo

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

Cambia un nombre de objeto relation alias

En el siguiente ejemplo, se cambia el nombre de todas las instancias del objeto relation alias de table a t.

Partes de nombre de origen y de destino

Parte de nombre	Origen	Target
Base de datos
Esquema
Relación	table	t
Atributo

Tipo

• relation alias

Entrada de ejemplo

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

Resultado de ejemplo

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

Cambia un nombre de objeto function

En el siguiente ejemplo, se cambia el nombre de mydb.myschema.myfunction a mydb.myschema.function1.

Partes de nombre de origen y de destino

Parte de nombre	Origen	Target
Base de datos	mydb	mydb
Esquema	myschema	myschema
Relación	myprocedure	procedure1
Atributo

Tipo

• function

Entrada de ejemplo

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

Resultado de ejemplo

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

Cambia un nombre de objeto attribute

En el siguiente ejemplo, se cambia el nombre de mydb.myschema.mytable.myfield a mydb.myschema.mytable.field1. Debido a que los objetos attribute están en el nivel más bajo de la jerarquía de objetos, esta asignación de nombres no cambia el nombre de ningún otro objeto.

Partes de nombre de origen y de destino

Parte de nombre	Origen	Target
Base de datos	mydb
Esquema	myschema
Relación	mytable
Atributo	myfield	field1

Tipo

• attribute

Entrada de ejemplo

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

Resultado de ejemplo

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

Cambia un nombre de objeto attribute alias

En el siguiente ejemplo, se cambia el nombre de mydb.myschema.mytable.myfield a mydb.myschema.mytable.field1. Debido a que los objetos attribute alias están en el nivel más bajo de la jerarquía de objetos, esta asignación de nombres no cambia el nombre de ningún otro objeto.

Partes de nombre de origen y de destino

Parte de nombre	Origen	Target
Base de datos	mydb
Esquema	myschema
Relación	mytable
Atributo	myfield	field1

Tipo

• attribute alias

Entrada de ejemplo

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

Resultado de ejemplo

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

Formato de archivo JSON

Si eliges especificar reglas de asignación de nombres mediante un archivo JSON en lugar de la consola de Google Cloud, el archivo JSON debe seguir este formato:

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

El tamaño del archivo debe ser inferior a 5 MB.

Si deseas obtener más información sobre cómo especificar reglas de asignación de nombres para un trabajo de traducción, consulta Envía un trabajo de traducción.

Ejemplos de JSON

En los siguientes ejemplos, se muestra cómo especificar reglas de asignación de nombres mediante archivos JSON.

Ejemplo 1

Las reglas de asignación de nombres de este ejemplo realizan los siguientes cambios de nombres de objeto:

• Cambia el nombre de las instancias del objeto project.dataset2.table2 relation a bq_project.bq_dataset2.bq_table2.
• Cambia el nombre de todas las instancias del objeto project database a bq_project. Por ejemplo, project.mydataset.table2 se convierte en bq_project.mydataset.table2, y CREATE DATASET project.mydataset se convierte en 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"
    }
  }]
}

Ejemplo 2

Las reglas de asignación de nombres de este ejemplo realizan los siguientes cambios de nombres de objeto:

• Cambia el nombre de las instancias del objeto project.dataset2.table2.field1 attribute a bq_project.bq_dataset2.bq_table2.bq_field en las declaraciones DDL y 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"
    }
  }]
}