Mapear nomes de objetos SQL para tradução em lote

Visualização

Este produto está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço Gerais" dos Termos Específicos do Serviço. Os produtos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Neste documento, descrevemos como configurar o mapeamento de nomes para renomear objetos SQL durante a tradução em lote.

Visão geral

O mapeamento de nomes permite identificar os nomes de objetos SQL nos arquivos de origem e especificar nomes de destino para esses objetos no BigQuery. É possível usar alguns ou todos os seguintes componentes para configurar o mapeamento de nome para um objeto:

• Uma regra de mapeamento de nome composta por:
  • Partes de nome de origem que fornecem o nome totalmente qualificado do objeto no sistema de origem.
  • Um tipo que identifica o tipo do objeto de origem.
  • Partes do nome de destino que fornecem o nome do objeto no BigQuery.
• Um nome de banco de dados padrão a ser usado com qualquer objeto de origem que não especifique um.
• Um nome de esquema padrão a ser usado com qualquer objeto de origem que não especifique um.

Partes de nome

Para fornecer os valores dos nomes de objetos de origem e de destino em uma regra de mapeamento de nome, use uma combinação das seguintes partes de nome:

• Banco de dados: o nível superior da hierarquia de nomes. Sua plataforma de origem pode usar um termo alternativo para isso, por exemplo, projeto.
• Esquema: o segundo nível da hierarquia de nomes. A plataforma de origem pode usar um termo alternativo para isso, por exemplo, conjunto de dados.
• Relação: o terceiro nível da hierarquia de nomenclatura. Sua plataforma de origem pode usar um termo alternativo para isso, por exemplo, tabela.
• Atributo: o nível mais baixo da hierarquia de nomes. A plataforma de origem pode usar um termo alternativo para isso, por exemplo, column.

Tipos de objeto

Também é preciso especificar o tipo de objeto de origem que você está renomeando em uma regra de mapeamento de nome. Os seguintes tipos de objetos são compatíveis:

• Database: um objeto de nível superior na hierarquia de objetos, por exemplo, database.schema.relation.attribute. Sua plataforma de origem pode usar um termo alternativo para isso, por exemplo, projeto. A especificação de database como o tipo de objeto muda todas as referências à string de origem em instruções DDL e DML.
• Schema: um objeto de segundo nível na hierarquia de objetos. A plataforma de origem pode usar um termo alternativo para isso, por exemplo, conjunto de dados. A especificação de schema como o tipo de objeto muda todas as referências à string de origem em instruções DDL e DML.
• Relation: um objeto de terceiro nível na hierarquia de objetos. Sua plataforma de origem pode usar um termo alternativo para isso, por exemplo, tabela. A especificação de relation como o tipo de objeto muda todas as referências à string de origem em instruções DDL.
• Relation alias: um alias para um objeto de terceiro nível. Por exemplo, na consulta SELECT t.field1, t.field2 FROM myTable t;, t é um alias de relação. Na consulta SELECT field1, field2 FROM schema1.table1, table1 também é um alias de relação. Especificar relation alias como o tipo de objeto cria aliases para todas as referências à string de origem em instruções DML. Por exemplo, se tableA for especificado como o nome do destino, os exemplos anteriores serão traduzidos como SELECT tableA.field1, tableA.field2 FROM myTable AS tableA; e SELECT tableA.field1, tableA.field2 FROM schema1.table1 AS tableA, respectivamente.
• Function: um procedimento, por exemplo, create procedure db.test.function1(a int). A especificação de function como o tipo de objeto muda todas as referências à string de origem em instruções DDL e DML.
• Attribute: um objeto de quarto nível na hierarquia de objetos. A plataforma de origem pode usar um termo alternativo para isso, por exemplo, column. A especificação de attribute como o tipo de objeto muda todas as referências à string de origem em instruções DDL.
• Attribute alias: um alias para um objeto de quarto nível. Por exemplo, na consulta SELECT field1 FROM myTable;, field1 é um alias de atributo. A especificação de attribute alias como o tipo de objeto muda todas as referências à string de origem em instruções DML.

Partes de nome necessárias para tipos de objeto

Para descrever um objeto em uma regra de mapeamento de nome, use as partes de nome identificadas para cada tipo de objeto na tabela a seguir:

Tipo	Nome do objeto de origem				Nome do objeto de destino
	Parte do nome do banco de dados	Parte do nome do esquema	Parte do nome da relação	Parte do nome do atributo	Parte do nome do banco de dados	Parte do nome do esquema	Parte do nome da relação	Parte do nome do 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

Banco de dados padrão

Se você quiser anexar um nome de projeto do BigQuery a todos os objetos traduzidos, o mais fácil é especificar um nome de banco de dados padrão ao criar um job de tradução. Isso funciona para arquivos de origem em que a nomenclatura de três partes é usada ou em que a nomeação de quatro partes é usada, mas o nome de objeto de nível mais alto não é especificado.

Por exemplo, se você especificar o nome de banco de dados padrão myproject, uma instrução como SELECT * FROM database.table será convertida em SELECT * FROM myproject.database.table. Se você tiver objetos que já usam uma parte do nome do banco de dados, como SELECT * FROM database.schema.table, use uma regra de mapeamento de nome para renomear database.schema.table como myproject.schema.table.

Esquema padrão

Para qualificar totalmente todos os nomes de objeto nos arquivos de origem que não usam nomeação de quatro partes, forneça um nome de banco de dados padrão e um nome de esquema padrão quando você cria um job de tradução. O nome de esquema padrão é fornecido como o primeiro nome de esquema na opção de caminho de pesquisa do esquema.

Por exemplo, se você especificar o nome padrão do banco de dados myproject e o nome padrão do esquema myschema, as seguintes instruções de origem:

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

Estão traduzidos para:

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

Comportamento da regra de mapeamento de nome

As seções a seguir descrevem como as regras de mapeamento de nome se comportam.

A herança de regras flui para baixo na hierarquia de objetos

Uma mudança de nome que afeta um objeto de nível superior afeta o objeto de destino e todos os objetos filhos dele na mesma hierarquia.

Por exemplo, se você especificar a seguinte regra de mapeamento de nome com um tipo de objeto schema:

Parte do nome	Origem	Objetivo
Banco de dados	sales_db	sales
Schema	cust_mgmt	cms
Relação
Atributo

Quando aplicado, as partes do nome do banco de dados e do esquema de todos os objetos relation e attribute no esquema sales_db.cust_mgmt também são alteradas. Por exemplo, um objeto relation chamado sales_db.cust_mgmt.history se torna sales.cms.history.

Por outro lado, as mudanças de nome que segmentam objetos de nível inferior não afetam os objetos de nível superior ou igual na hierarquia de objetos.

Por exemplo, se você especificar a seguinte regra de mapeamento de nome com um tipo de objeto relation:

Parte do nome	Origem	Objetivo
Banco de dados	sales_db	sales
Schema	cust_mgmt	cms
Relação	clients	accounts
Atributo

Quando aplicado, nenhum outro objeto no nível da hierarquia de sales_db ou sales_db.cust_mgmt tem o nome alterado.

A regra mais específica é aplicada

Apenas uma regra de mapeamento de nome é aplicada a um objeto. Se várias regras puderem afetar um único objeto, a regra que afeta a parte do nome de nível mais baixo será aplicada. Por exemplo, se uma regra de mapeamento de nome de tipo database e uma regra de mapeamento de nome de tipo schema podem afetar o nome de um objeto relation, a regra de mapeamento de nome de tipo schema será aplicada.

Usar uma combinação única de tipos e valores de origem

Não é possível especificar mais de uma regra de mapeamento de nome com o mesmo tipo e valores de origem. Por exemplo, não é possível especificar as duas regras de mapeamento de nome a seguir:

	Regra 1, digite attribute		Regra 2, digite attribute
Parte do nome	Origem	Objetivo	Origem	Objetivo
Banco de dados	project		project
Schema	dataset1		dataset1
Relação	table1		table1
Atributo	lname	last_name	lname	lastname

Criar regras de mapeamento de nome correspondentes a attribute e attribute alias

Ao usar uma regra de mapeamento de nome de tipo attribute para alterar um nome de atributo em instruções DDL, também é necessário criar uma regra de mapeamento de nome attribute alias para alterar o nome desse atributo nas instruções DML.

Alterações de nome não são aplicadas em cascata

As alterações de nome não são aplicadas em cascata nas regras de nome. Por exemplo, se você tiver criado uma regra de mapeamento de nome que renomeia database1 como project1 e outra que renomeia project1 para project2, o tradutor não mapeia database1 para project2.

Processar objetos de origem que não têm nomes de quatro partes

Alguns sistemas de origem, como o Teradata, usam três partes de nome para qualificar totalmente os nomes de objetos. Muitos sistemas de origem também permitem usar nomes parcialmente qualificados nos dialetos SQL, por exemplo, usando database1.schema1.table1, schema1.table1 e table1 para se referir ao mesmo objeto em contextos diferentes. Se os arquivos de origem tiverem objetos que não usam nomes de objetos de quatro partes, é possível usar o mapeamento de nomes em combinação especificando um nome de banco de dados padrão e um nome do esquema padrão para fazer o mapeamento de nomes que você quer.

Para ver exemplos de como usar regras de mapeamento de nome com um nome padrão de banco de dados ou de esquema padrão, consulte Alterar a parte do nome do banco de dados para objetos com níveis variados de conclusão de nome e Alterar um nome de objeto de relação parcialmente qualificado.

Exemplos de mapeamento de nome

Use os exemplos nesta seção para ver como as regras de mapeamento de nome funcionam em casos de uso comuns.

Alterar a parte do nome do banco de dados para objetos totalmente qualificados

O exemplo a seguir renomeia a parte do nome do banco de dados de td_project para bq_project para todos os objetos database, schema, relation e function que têm nomes qualificados.

Partes de nome de origem e destino

Parte do nome	Origem	Objetivo
Banco de dados	td_project	bq_project
Schema
Relação
Atributo

Tipo

• database

Exemplo de entrada

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

Exemplo de saída

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

Alterar a parte do nome do banco de dados para objetos com níveis variados de conclusão de nome

O exemplo a seguir renomeia a parte do nome do banco de dados project para bq_project para todos os tipos de objeto e também adiciona bq_project como a parte do nome do banco de dados para objetos que não especificam uma.

Para fazer isso, é preciso especificar um valor padrão de banco de dados ao configurar o job de tradução, além de especificar regras de mapeamento de nome. Para mais informações sobre como especificar um nome de banco de dados padrão, consulte Enviar um job de tradução.

Valor padrão do banco de dados

• project

Partes de nome de origem e destino

Parte do nome	Origem	Objetivo
Banco de dados	project	bq_project
Schema
Relação
Atributo

Tipo

• database

Exemplo de entrada

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

Exemplo de saída

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

Alterar a parte do nome do banco de dados e a parte do nome do esquema para objetos totalmente qualificados

O exemplo a seguir altera a parte do nome do banco de dados warehouse1 para myproject e também a parte do nome do esquema database1 para mydataset.

Também é possível mudar as partes de um nome de objeto relation da mesma maneira usando um tipo relation e especificando valores de origem e destino para a parte do nome da relação.

Partes de nome de origem e destino

Parte do nome	Origem	Objetivo
Banco de dados	warehouse1	myproject
Schema	database1	mydataset
Relação
Atributo

Tipo

• schema

Exemplo de entrada

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

Exemplo de saída

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

Alterar um nome de objeto relation totalmente qualificado

O exemplo a seguir renomeia mydb.myschema.mytable como mydb.myschema.table1.

Partes de nome de origem e destino

Parte do nome	Origem	Objetivo
Banco de dados	mydb	mydb
Schema	myschema	myschema
Relação	mytable	table1
Atributo

Tipo

• relation

Exemplo de entrada

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

Exemplo de saída

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

Mudar um nome de objeto relation parcialmente qualificado

O exemplo a seguir renomeia myschema.mytable como mydb.myschema.table1.

Valor padrão do banco de dados

• mydb

Partes de nome de origem e destino

Parte do nome	Origem	Objetivo
Banco de dados	mydb	mydb
Schema	myschema	myschema
Relação	mytable	table1
Atributo

Tipo

• relation

Exemplo de entrada

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

Exemplo de saída

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

Mudar o nome de um objeto relation alias

O exemplo a seguir renomeia todas as instâncias do objeto relation alias table para t.

Partes de nome de origem e destino

Parte do nome	Origem	Objetivo
Banco de dados
Schema
Relação	table	t
Atributo

Tipo

• relation alias

Exemplo de entrada

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

Exemplo de saída

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

Mudar o nome de um objeto function

O exemplo a seguir renomeia mydb.myschema.myfunction como mydb.myschema.function1.

Partes de nome de origem e destino

Parte do nome	Origem	Objetivo
Banco de dados	mydb	mydb
Schema	myschema	myschema
Relação	myprocedure	procedure1
Atributo

Tipo

• function

Exemplo de entrada

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

Exemplo de saída

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

Mudar o nome de um objeto attribute

O exemplo a seguir renomeia mydb.myschema.mytable.myfield como mydb.myschema.mytable.field1. Como os objetos attribute estão no nível mais baixo da hierarquia de objetos, esse mapeamento de nome não altera o nome de nenhum outro objeto.

Partes de nome de origem e destino

Parte do nome	Origem	Objetivo
Banco de dados	mydb
Schema	myschema
Relação	mytable
Atributo	myfield	field1

Tipo

• attribute

Exemplo de entrada

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

Exemplo de saída

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

Mudar o nome de um objeto attribute alias

O exemplo a seguir renomeia mydb.myschema.mytable.myfield como mydb.myschema.mytable.field1. Como os objetos attribute alias estão no nível mais baixo da hierarquia de objetos, esse mapeamento de nome não altera o nome de nenhum outro objeto.

Partes de nome de origem e destino

Parte do nome	Origem	Objetivo
Banco de dados	mydb
Schema	myschema
Relação	mytable
Atributo	myfield	field1

Tipo

• attribute alias

Exemplo de entrada

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

Exemplo de saída

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

Formato de arquivo JSON

Se você optar por especificar regras de mapeamento de nome usando um arquivo JSON em vez do console do Google Cloud, o arquivo JSON precisará 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"
      }
    }
  ]
}

O tamanho do arquivo precisa ser inferior a 5 MB.

Para mais informações sobre como especificar regras de mapeamento de nome para um job de tradução, consulte Enviar um job de tradução.

Exemplos JSON

Os exemplos a seguir mostram como especificar regras de mapeamento de nome usando arquivos JSON.

Exemplo 1

As regras de mapeamento de nome neste exemplo fazem as seguintes mudanças no nome do objeto:

• Renomeia as instâncias do objeto project.dataset2.table2 relation como bq_project.bq_dataset2.bq_table2.
• Renomeia todas as instâncias do objeto project database para bq_project. Por exemplo, project.mydataset.table2 se torna bq_project.mydataset.table2 e CREATE DATASET project.mydataset se torna 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"
    }
  }]
}

Exemplo 2

As regras de mapeamento de nome neste exemplo fazem as seguintes mudanças no nome do objeto:

• Renomeia as instâncias do objeto attribute project.dataset2.table2.field1 para bq_project.bq_dataset2.bq_table2.bq_field nas instruções DDL e 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"
    }
  }]
}