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

Pré-visualização

Este produto está sujeito aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. Os produtos pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Nota: o mapeamento de nomes de objetos através de JSON só é suportado pela API de processamento em lote antiga. Se estiver a usar a API BigQuery Migration ou a iniciar tarefas em lote a partir da Google Cloud consola, use o mapeamento de nomes de objetos baseado em YAML em alternativa.

Este documento descreve como configurar o mapeamento de nomes para mudar o nome de objetos SQL durante a tradução em lote.

Vista geral

O mapeamento de nomes permite-lhe identificar os nomes dos objetos SQL nos seus ficheiros de origem e especificar nomes de destino para esses objetos no BigQuery. Pode usar alguns ou todos os seguintes componentes para configurar o mapeamento de nomes de um objeto:

• Uma regra de mapeamento de nomes, composta por:
  • Partes do 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.
  • Segmente partes do nome que fornecem o nome do objeto no BigQuery.
• Um nome de base de dados predefinida a usar com quaisquer objetos de origem que não especifiquem um.
• Um nome de esquema predefinido a usar com quaisquer objetos de origem que não especifiquem um.

Nome das peças

Fornece os valores para os nomes dos objetos de origem e de destino numa regra de mapeamento de nomes usando uma combinação das seguintes partes do nome:

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

Tipos de objetos

Também tem de especificar o tipo de objeto de origem que está a mudar o nome numa regra de mapeamento de nomes. São suportados os seguintes tipos de objetos:

• Database: um objeto de nível superior na hierarquia de objetos, por exemplo, database.schema.relation.attribute. A sua plataforma de origem pode usar um termo alternativo para isto, por exemplo, projeto. A especificação de database como o tipo de objeto altera todas as referências à string de origem nas declarações DDL e DML.
• Schema: um objeto de segundo nível na hierarquia de objetos. A sua plataforma de origem pode usar um termo alternativo para isto, por exemplo, conjunto de dados. A especificação de schema como o tipo de objeto altera todas as referências à string de origem nas declarações DDL e DML.
• Relation: um objeto de terceiro nível na hierarquia de objetos. A sua plataforma de origem pode usar um termo alternativo para isto, por exemplo, tabela. A especificação de relation como o tipo de objeto altera todas as referências à string de origem nas declaraçõ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. A especificação de relation alias como o tipo de objeto cria alias para todas as referências à string de origem nas declarações DML. Por exemplo, se tableA for especificado como o nome de destino, os exemplos anteriores são traduzidos como SELECT tableA.field1, tableA.field2 FROM myTable AS tableA; e SELECT tableA.field1, tableA.field2 FROM schema1.table1 AS tableA, respetivamente.
• Function: um procedimento, por exemplo, create procedure db.test.function1(a int). A especificação de function como o tipo de objeto altera todas as referências à string de origem nas declarações DDL e DML.
• Attribute: um objeto de quarto nível na hierarquia de objetos. A sua plataforma de origem pode usar um termo alternativo para isto, por exemplo, coluna. A especificação de attribute como o tipo de objeto altera todas as referências à string de origem nas declaraçõ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 altera todas as referências à string de origem nas declarações DML.

Partes do nome obrigatórias para tipos de objetos

Para descrever um objeto numa regra de mapeamento de nomes, use as partes do nome identificadas para cada tipo de objeto na tabela seguinte:

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

Base de dados predefinida

Se quiser anexar um nome de projeto do BigQuery a todos os objetos traduzidos, a forma mais fácil de o fazer é especificar um nome de base de dados predefinido quando criar uma tarefa de tradução. Isto funciona para ficheiros de origem em que é usada a nomenclatura de três partes ou em que é usada a nomenclatura de quatro partes, mas o nome do objeto de nível mais elevado não está especificado.

Por exemplo, se especificar o nome da base de dados predefinido myproject, uma declaração de origem como SELECT * FROM database.table é traduzida para SELECT * FROM myproject.database.table. Se tiver objetos que já usam uma parte do nome da base de dados, como SELECT * FROM database.schema.table, tem de usar uma regra de mapeamento de nomes para mudar o nome de database.schema.table para myproject.schema.table.

Esquema predefinido

Se quiser qualificar totalmente todos os nomes de objetos nos ficheiros de origem que não usam a nomenclatura de quatro partes, pode fornecer um nome da base de dados predefinido e um nome do esquema predefinido quando criar uma tarefa de tradução. O nome do esquema predefinido é fornecido como o primeiro nome do esquema na opção de caminho de pesquisa do esquema.

Por exemplo, se especificar o nome da base de dados predefinido myproject e o nome do esquema predefinido myschema, as seguintes declarações de origem:

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

São traduzidas para:

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

Comportamento da regra de mapeamento de nomes

As secções seguintes descrevem o comportamento das regras de mapeamento de nomes.

A herança de regras flui na hierarquia de objetos

Uma alteração de nome que afeta um objeto de nível superior afeta o objeto de destino e também todos os respetivos objetos secundários na mesma hierarquia.

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

Parte do nome	Fonte	Alvo
Bases de dados	sales_db	sales
Esquema	cust_mgmt	cms
Relação
Atributo

Quando é aplicado, os nomes das partes da base de dados e do esquema de todos os objetos relation e attribute no esquema sales_db.cust_mgmt também são alterados. Por exemplo, um objeto relation com o nome sales_db.cust_mgmt.history torna-se sales.cms.history.

Por outro lado, as alterações de nomes que têm como alvo objetos de nível inferior não afetam os objetos de nível superior ou do mesmo nível na hierarquia de objetos.

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

Parte do nome	Fonte	Alvo
Bases de dados	sales_db	sales
Esquema	cust_mgmt	cms
Relação	clients	accounts
Atributo

Quando é aplicado, o nome de nenhum outro objeto ao nível da hierarquia de objetos sales_db ou sales_db.cust_mgmt é alterado.

É aplicada a regra mais específica

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

Use uma combinação única de valores de tipo e origem

Não pode especificar mais do que uma regra de mapeamento de nomes com o mesmo tipo e valores de origem. Por exemplo, não pode especificar as seguintes regras de mapeamento de nomes:

	Regra 1, tipo attribute		Regra 2, tipo attribute
Parte do nome	Fonte	Alvo	Fonte	Alvo
Bases de dados	project		project
Esquema	dataset1		dataset1
Relação	table1		table1
Atributo	lname	last_name	lname	lastname

Crie regras de mapeamento de nomes attribute e attribute alias correspondentes

Quando usa uma regra de mapeamento de nomes do tipo attribute para alterar o nome de um atributo em declarações DDL, tem de criar uma regra de mapeamento de nomes do tipo attribute alias para alterar também o nome desse atributo em declarações DML.

As alterações de nomes não são propagadas

As alterações de nomes não são aplicadas em cascata nas regras de nomes. Por exemplo, se criou uma regra de mapeamento de nomes que muda o nome de database1 para project1 e outra que muda o nome de project1 para project2, o tradutor não mapeia database1 para project2.

Trate objetos de origem que não tenham nomes de quatro partes

Alguns sistemas de origem, como o Teradata, usam três partes do nome para qualificar totalmente os nomes dos objetos. Muitos sistemas de origem também permitem usar nomes parcialmente qualificados nos respetivos dialetos SQL, por exemplo, usar database1.schema1.table1, schema1.table1 e table1 para se referir ao mesmo objeto em contextos diferentes. Se os seus ficheiros de origem contiverem objetos que não usam nomes de objetos de quatro partes, pode usar o mapeamento de nomes em combinação com a especificação de um nome da base de dados predefinido e um nome do esquema predefinido para conseguir o mapeamento de nomes que quer.

Para ver exemplos de utilização de regras de mapeamento de nomes com um nome da base de dados predefinido ou um nome do esquema predefinido, consulte os artigos Alterar a parte do nome da base de dados para objetos com vários níveis de conclusão de nomes e Alterar um nome de objeto de relação parcialmente qualificado.

Exemplos de mapeamento de nomes

Use os exemplos nesta secção para ver como funcionam as regras de mapeamento de nomes para exemplos de utilização comuns.

Altere a parte do nome da base de dados para objetos totalmente qualificados

O exemplo seguinte muda o nome da parte do nome da base de dados de td_project para bq_project para todos os objetos database, schema, relation e function que tenham nomes totalmente qualificados.

Partes dos nomes de origem e de destino

Parte do nome	Fonte	Alvo
Bases de dados	td_project	bq_project
Esquema
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

Altere a parte do nome da base de dados para objetos com níveis variáveis de conclusão de nomes

O exemplo seguinte muda o nome da parte project do nome da base de dados para bq_project para todos os tipos de objetos e também adiciona bq_project como a parte do nome da base de dados para objetos que não especificam um.

Para tal, tem de especificar um valor predefinido da base de dados quando configurar a tarefa de tradução, além de especificar regras de mapeamento de nomes. Para mais informações sobre como especificar um nome de base de dados predefinido, consulte o artigo Envie uma tarefa de tradução.

Valor predefinido da base de dados

• project

Partes dos nomes de origem e de destino

Parte do nome	Fonte	Alvo
Bases de dados	project	bq_project
Esquema
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

Altere a parte do nome da base de dados e a parte do nome do esquema para objetos totalmente qualificados

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

Também pode alterar as partes de um nome de objeto relation da mesma forma, usando um tipo relation e especificando valores de origem e destino para a parte do nome da relação.

Partes dos nomes de origem e de destino

Parte do nome	Fonte	Alvo
Bases de dados	warehouse1	myproject
Esquema	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;

Altere um relation nome de objeto totalmente qualificado

O exemplo seguinte muda o nome de mydb.myschema.mytable para mydb.myschema.table1.

Partes dos nomes de origem e de destino

Parte do nome	Fonte	Alvo
Bases de dados	mydb	mydb
Esquema	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));

Altere um nome de objeto relation parcialmente qualificado

O exemplo seguinte muda o nome de myschema.mytable para mydb.myschema.table1.

Valor predefinido da base de dados

• mydb

Partes dos nomes de origem e de destino

Parte do nome	Fonte	Alvo
Bases de dados	mydb	mydb
Esquema	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));

Altere o nome de um objeto relation alias

O exemplo seguinte muda o nome de todas as instâncias do objeto relation aliastable para t.

Partes dos nomes de origem e de destino

Parte do nome	Fonte	Alvo
Bases de dados
Esquema
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

Altere o nome de um objeto function

O exemplo seguinte muda o nome de mydb.myschema.myfunction para mydb.myschema.function1.

Partes dos nomes de origem e de destino

Parte do nome	Fonte	Alvo
Bases de dados	mydb	mydb
Esquema	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);

Altere o nome de um objeto attribute

O exemplo seguinte muda o nome de mydb.myschema.mytable.myfield para mydb.myschema.mytable.field1. Uma vez que os objetos attribute estão no nível mais baixo da hierarquia de objetos, este mapeamento de nomes não altera o nome de nenhum outro objeto.

Partes dos nomes de origem e de destino

Parte do nome	Fonte	Alvo
Bases de dados	mydb
Esquema	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);

Altere o nome de um objeto attribute alias

O exemplo seguinte muda o nome de mydb.myschema.mytable.myfield para mydb.myschema.mytable.field1. Uma vez que os objetos attribute alias estão no nível mais baixo da hierarquia de objetos, esta associação de nomes não altera o nome de nenhum outro objeto.

Partes dos nomes de origem e de destino

Parte do nome	Fonte	Alvo
Bases de dados	mydb
Esquema	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 ficheiro JSON

Se optar por especificar regras de mapeamento de nomes através de um ficheiro JSON em vez da Google Cloud consola, o ficheiro JSON tem de 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 ficheiro tem de ser inferior a 5 MB.

Para mais informações sobre como especificar regras de mapeamento de nomes para uma tarefa de tradução, consulte o artigo Envie uma tarefa de tradução.

Exemplos JSON

Os exemplos seguintes mostram como especificar regras de mapeamento de nomes através de ficheiros JSON.

Exemplo 1

As regras de mapeamento de nomes neste exemplo fazem as seguintes alterações aos nomes dos objetos:

• Mude o nome das instâncias do objeto project.dataset2.table2 relation para bq_project.bq_dataset2.bq_table2.
• Muda o nome de todas as instâncias do objeto project database para bq_project. Por exemplo, project.mydataset.table2 passa a bq_project.mydataset.table2, e CREATE DATASET project.mydataset passa a 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 nomes neste exemplo fazem as seguintes alterações aos nomes dos objetos:

• Mude o nome das instâncias do objeto project.dataset2.table2.field1 attribute 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"
    }
  }]
}