バッチ変換のために SQL オブジェクト名をマッピングする

このドキュメントでは、バッチ変換中に SQL オブジェクトの名前を変更するように名前マッピングを構成する方法について説明します。

概要

名前マッピングを使用すると、ソースファイル内の SQL オブジェクトの名前を識別し、BigQuery 内のそれらのオブジェクトのターゲット名を指定できます。次のコンポーネントの一部またはすべてを使用して、オブジェクトの名前マッピングを構成できます。

名前マッピングルールは、次のもので構成されます。
- ソースシステム内のオブジェクトの完全修飾名を指定する、ソースの名前の要素。
- ソースオブジェクトのタイプを識別する型。
- BigQuery でオブジェクトの名前を指定するターゲットの名前の要素。
値を指定しないソースオブジェクトで使用する、デフォルトのデータベース名。
値を指定しないソースオブジェクトで使用する、デフォルトのスキーマ名。

名前の要素

名前マッピングルールでソースとターゲットのオブジェクト名の値を指定するには、次の名前の要素を組み合わせて使用します。

データベース: 命名階層の最上位。ソースプラットフォームによっては、プロジェクトなど、別の用語が使用されることがあります。
スキーマ: 命名階層の第 2 レベル。ソースプラットフォームによっては、データセットなど、別の用語が使用されることがあります。
リレーション: 命名階層の第 3 レベル。ソースプラットフォームによっては、テーブルなど、別の用語が使用されることがあります。
属性: 命名階層の最下位レベル。ソースプラットフォームによっては、列など、別の用語が使用されることがあります。

オブジェクトタイプ

名前マッピングルールで、名前を変更するソースオブジェクトのタイプも指定する必要があります。次のオブジェクトタイプがサポートされています。

Database: オブジェクト階層の最上位のオブジェクト（database.schema.relation.attribute など）。ソースプラットフォームによっては、プロジェクトなど、別の用語が使用されることがあります。オブジェクトタイプとして database を指定すると、DDL ステートメントと DML ステートメントの両方でソース文字列へのすべての参照が変更されます。
Schema: オブジェクト階層内の第 2 レベルのオブジェクト。ソースプラットフォームによっては、データセットなど、別の用語が使用されることがあります。オブジェクトタイプとして schema を指定すると、DDL ステートメントと DML ステートメントの両方でソース文字列へのすべての参照が変更されます。
Relation: オブジェクト階層内の第 3 レベルのオブジェクト。ソースプラットフォームによっては、テーブルなど、別の用語が使用されることがあります。オブジェクトタイプとして relation を指定すると、DDL ステートメントでソース文字列へのすべての参照が変更されます。
Relation alias: 第 3 レベルのオブジェクトのエイリアス。たとえば、クエリ SELECT t.field1, t.field2 FROM myTable t; では、t はリレーションエイリアスです。クエリ SELECT field1, field2 FROM schema1.table1 では、table1 もリレーションエイリアスです。オブジェクトタイプとして relation alias を指定すると、DML ステートメントのソース文字列へのすべての参照にエイリアスが作成されます。たとえば、tableA がターゲット名として指定されている場合、上記の例はそれぞれ SELECT tableA.field1, tableA.field2 FROM myTable AS tableA; と SELECT tableA.field1, tableA.field2 FROM schema1.table1 AS tableA に変換されます。
Function: プロシージャ（create procedure db.test.function1(a int) など）。オブジェクトタイプとして function を指定すると、DDL ステートメントと DML ステートメントの両方でソース文字列へのすべての参照が変更されます。
Attribute: オブジェクト階層内の第 4 レベルのオブジェクト。ソースプラットフォームによっては、列など、別の用語が使用されることがあります。オブジェクトタイプとして attribute を指定すると、DDL ステートメントでソース文字列へのすべての参照が変更されます。
Attribute alias: 第 4 レベルのオブジェクトのエイリアス。たとえば、クエリ SELECT field1 FROM myTable; では、field1 が属性エイリアスです。オブジェクトタイプとして attribute alias を指定すると、DDL ステートメントでソース文字列へのすべての参照が変更されます。

オブジェクトタイプの必須の名前要素

名前マッピングルールでオブジェクトを記述するには、次の表の各オブジェクトタイプに対して識別される名前要素を使用します。

型	ソースオブジェクト名				ターゲットオブジェクト名
	データベース名の要素	スキーマ名の要素	リレーション名の要素	属性名の要素	データベース名の要素	スキーマ名の要素	リレーション名の要素	属性名の要素
`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

デフォルトのデータベース

変換されたすべてのオブジェクトに BigQuery プロジェクト名を追加する場合、最も簡単な方法は、変換ジョブの作成時にデフォルトのデータベース名を指定することです。これは、3 部構成の命名が使用されている、または 4 部構成の命名が使用されていて最高レベルのオブジェクト名が指定されていないソースファイルで機能します。

たとえば、デフォルトのデータベース名 myproject を指定すると、SELECT * FROM database.table などのソースステートメントは SELECT * FROM myproject.database.table に変換されます。すでにデータベース名の部分（SELECT * FROM database.schema.table など）を使用しているオブジェクトがある場合は、名前マッピングルールを使用して database.schema.table の名前を myproject.schema.table に変更する必要があります。

デフォルトスキーマ

4 つの要素から成る命名を使用しないソースファイル内のすべてのオブジェクト名を完全修飾する場合は、変換ジョブの作成時にデフォルトデータベース名とデフォルトのスキーマ名の両方を指定できます。スキーマの検索パスオプションの最初のスキーマ名として、デフォルトのスキーマ名が指定されています。

たとえば、デフォルトのデータベース名 myproject とデフォルトのスキーマ名 myschema を指定した場合、次のソースステートメント:

SELECT * FROM database.table
SELECT * FROM table1

は、次のように変換されます。

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

名前マッピングルールの動作

以降のセクションでは、名前マッピングルールの動作について説明します。

ルールの継承はオブジェクト階層を下る

上位オブジェクトに影響を与える名前の変更は、ターゲットオブジェクトだけでなく、同じ階層内のすべての子オブジェクトにも影響を与えます。

例: オブジェクトタイプ schema で次の名前マッピングルールを指定した場合。

名前要素	ソース	ターゲット
データベース	`sales_db`	`sales`
スキーマ	`cust_mgmt`	`cms`
リレーション
属性

これを適用すると、sales_db.cust_mgmt スキーマのすべての relation オブジェクトと attribute オブジェクトのデータベースとスキーマ名の部分も変更されます。たとえば、sales_db.cust_mgmt.history という名前の relation オブジェクトは sales.cms.history になります。

逆に、下位レベルのオブジェクトを対象とする名前の変更は、オブジェクト階層の上位または同じレベルのオブジェクトには影響しません。

例: オブジェクトタイプ relation で次の名前マッピングルールを指定した場合。

名前要素	ソース	ターゲット
データベース	`sales_db`	`sales`
スキーマ	`cust_mgmt`	`cms`
リレーション	`clients`	`accounts`
属性

これを適用しても、オブジェクト階層の sales_db レベルまたは sales_db.cust_mgmt レベルの他のオブジェクトの名前は変更されません。

最も狭い範囲のルールが適用されます

1 つのオブジェクトに適用される名前マッピングルールは 1 つだけです。複数のルールが 1 つのオブジェクトに影響する可能性がある場合、最下位レベルの名前部分に影響するルールが適用されます。たとえば、database タイプ名のマッピングルールと schema タイプ名のマッピングルールの両方が relation オブジェクトの名前に影響する可能性がある場合、schema タイプ名のマッピングは、ルールが適用されます。

型とソースの値の一意の組み合わせを使用する

同じタイプとソース値で複数の名前マッピングルールを指定することはできません。たとえば、次の名前マッピングルールを両方とも指定することはできません。

	ルール 1、タイプ `attribute`		ルール 2、タイプ `attribute`
名前要素	ソース	ターゲット	ソース	ターゲット
データベース	`project`		`project`
スキーマ	`dataset1`		`dataset1`
リレーション	`table1`		`table1`
属性	`lname`	`last_name`	`lname`	`lastname`

一致する `attribute` と `attribute alias` の名前マッピングルールを作成する

attribute 型名マッピングルールを使用して DDL ステートメントで属性名を変更する場合は、attribute alias 名前マッピングルールを作成して、DML ステートメントでもその属性名を変更する必要があります。

名前の変更はカスケードされません

名前の変更は、名前ルール全体にカスケードされません。たとえば、database1 を project1 に名前変更する名前マッピングルールと、project1 を project2 に名前変更する別の名前マッピングルールを作成した場合、変換ツールは database1 を project2 にマッピングしません。

4 つの要素からなる名前を持たないソースオブジェクトを処理する

Teradata などの一部のソースシステムでは、3 つの名前要素を使用してオブジェクト名を完全修飾します。多くのソースシステムでは、SQL 言語で部分的に修飾された名前を使用することもできます。たとえば、database1.schema1.table1、schema1.table1、table1 を使用して、異なるコンテキストの同じオブジェクトを参照できます。ソースファイルに 4 つの要素からなるオブジェクト名を使用しないオブジェクトが含まれている場合は、名前マッピングをデフォルトのデータベース名とデフォルトのスキーマ名と組み合わせて使用して、必要な名前マッピングを作成します。

デフォルトのデータベース名またはデフォルトのスキーマ名を持つ名前マッピングルールの使用例については、名前補完のレベルが異なるオブジェクトのデータベース名要素を変更するおよび部分的に修飾されたリレーションオブジェクト名を変更するを参照してください。

名前マッピングの例

このセクションの例を使用して、一般的なユースケースで名前マッピングルールがどのように機能するかを確認します。

完全修飾オブジェクトのデータベース名要素を変更する

次の例では、完全修飾名を持つすべての database、schema、relation、function オブジェクトのデータベース名の一部を td_project から bq_project に変更しています。

ソースとターゲットの名前要素

名前要素	ソース	ターゲット
データベース	`td_project`	`bq_project`
スキーマ
リレーション
属性

型

database

入力例

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

出力例

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

名前補完のレベルが異なるオブジェクトのデータベース名要素を変更する

次の例では、すべてのオブジェクトタイプについてデータベース名の要素 project を bq_project に変更し、何も指定していないオブジェクトのデータベース名の要素として bq_project を追加します。

これを行うには、変換ジョブの構成時に、名前のマッピングルールを指定するだけでなく、デフォルトのデータベース値を指定する必要があります。デフォルトのデータベース名を指定する方法については、変換ジョブを送信するをご覧ください。

デフォルトのデータベース値

project

ソースとターゲットの名前要素

名前要素	ソース	ターゲット
データベース	`project`	`bq_project`
スキーマ
リレーション
属性

型

database

入力例

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

出力例

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

完全修飾オブジェクトのデータベース名要素とスキーマ名要素を変更する

次の例では、データベース名要素 warehouse1 を myproject に変更し、database1 スキーマ名要素を mydataset に変更します。

relation オブジェクト名の要素についても、relation 型を使用し、リレーション名要素のソースとターゲットの値を指定することにより、同じように変更できます。

ソースとターゲットの名前要素

名前要素	ソース	ターゲット
データベース	`warehouse1`	`myproject`
スキーマ	`database1`	`mydataset`
リレーション
属性

型

schema

入力例

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

出力例

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

完全修飾の `relation` オブジェクト名を変更する

次の例では、mydb.myschema.mytable の名前を mydb.myschema.table1 に変更します。

ソースとターゲットの名前要素

名前要素	ソース	ターゲット
データベース	`mydb`	`mydb`
スキーマ	`myschema`	`myschema`
リレーション	`mytable`	`table1`
属性

型

relation

入力例

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

出力例

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

部分的に修飾された `relation` オブジェクト名を変更する

次の例では、myschema.mytable の名前を mydb.myschema.table1 に変更します。

デフォルトのデータベース値

mydb

ソースとターゲットの名前要素

名前要素	ソース	ターゲット
データベース	`mydb`	`mydb`
スキーマ	`myschema`	`myschema`
リレーション	`mytable`	`table1`
属性

型

relation

入力例

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

出力例

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

`relation alias` オブジェクト名を変更する

次の例では、relation alias オブジェクト table のすべてのインスタンスの名前を t に変更しています。

ソースとターゲットの名前要素

名前要素	ソース	ターゲット
データベース
スキーマ
リレーション	`table`	`t`
属性

型

relation alias

入力例

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

出力例

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

`function` オブジェクト名を変更する

次の例では、mydb.myschema.myfunction の名前を mydb.myschema.function1 に変更します。

ソースとターゲットの名前要素

名前要素	ソース	ターゲット
データベース	`mydb`	`mydb`
スキーマ	`myschema`	`myschema`
リレーション	`myprocedure`	`procedure1`
属性

型

function

入力例

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

出力例

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

`attribute` オブジェクト名を変更する

次の例では、mydb.myschema.mytable.myfield の名前を mydb.myschema.mytable.field1 に変更します。attribute オブジェクトはオブジェクト階層の最下位レベルにあるため、この名前マッピングによって他のオブジェクトの名前が変更されることはありません。

ソースとターゲットの名前要素

名前要素	ソース	ターゲット
データベース	`mydb`
スキーマ	`myschema`
リレーション	`mytable`
属性	`myfield`	`field1`

型

attribute

入力例

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

出力例

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

`attribute alias` オブジェクト名を変更する

次の例では、mydb.myschema.mytable.myfield の名前を mydb.myschema.mytable.field1 に変更します。attribute alias オブジェクトはオブジェクト階層の最下位レベルにあるため、この名前マッピングによって他のオブジェクトの名前が変更されることはありません。

ソースとターゲットの名前要素

名前要素	ソース	ターゲット
データベース	`mydb`
スキーマ	`myschema`
リレーション	`mytable`
属性	`myfield`	`field1`

型

attribute alias

入力例

SELECT myfield, name FROM mydb.myschema.mytable;

出力例

SELECT field1, name FROM mydb.myschema.mytable;

JSON ファイル形式

Google Cloud コンソールではなく JSON ファイルを使用して名前マッピングルールを指定する場合は、JSON ファイルは次の形式に従う必要があります。

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

ファイルサイズは 5 MB 未満である必要があります。

変換ジョブの名前マッピングルールを指定する方法については、変換ジョブを送信するをご覧ください。

JSON の例

次の例は、JSON ファイルを使用して名前マッピングルールを指定する方法を示しています。

例 1

この例の名前マッピングルールでは、オブジェクト名を次のように変更します。

project.dataset2.table2 relation オブジェクトのインスタンスの名前を bq_project.bq_dataset2.bq_table2 に変更します。
project database オブジェクトのすべてのインスタンスの名前を bq_project に変更します。たとえば、project.mydataset.table2 は bq_project.mydataset.table2 に、CREATE DATASET project.mydataset は 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"
    }
  }]
}

例 2

この例の名前マッピングルールでは、オブジェクト名を次のように変更します。

DDL ステートメントと DML ステートメントの両方で、project.dataset2.table2.field1 attribute オブジェクトのインスタンスを bq_project.bq_dataset2.bq_table2.bq_field に名前変更します。

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

バッチ変換のために SQL オブジェクト名をマッピングする

概要

名前の要素

オブジェクト タイプ

オブジェクト タイプの必須の名前要素

デフォルトのデータベース

デフォルト スキーマ

名前マッピング ルールの動作

ルールの継承はオブジェクト階層を下る

最も狭い範囲のルールが適用されます

型とソースの値の一意の組み合わせを使用する

一致する attribute と attribute alias の名前マッピング ルールを作成する

名前の変更はカスケードされません

4 つの要素からなる名前を持たないソース オブジェクトを処理する

名前マッピングの例

完全修飾オブジェクトのデータベース名要素を変更する

名前補完のレベルが異なるオブジェクトのデータベース名要素を変更する

完全修飾オブジェクトのデータベース名要素とスキーマ名要素を変更する

完全修飾の relation オブジェクト名を変更する

部分的に修飾された relation オブジェクト名を変更する

relation alias オブジェクト名を変更する

function オブジェクト名を変更する

attribute オブジェクト名を変更する

attribute alias オブジェクト名を変更する

JSON ファイル形式

JSON の例

例 1

例 2

オブジェクトタイプ

オブジェクトタイプの必須の名前要素

デフォルトスキーマ

名前マッピングルールの動作

一致する `attribute` と `attribute alias` の名前マッピングルールを作成する

4 つの要素からなる名前を持たないソースオブジェクトを処理する

完全修飾の `relation` オブジェクト名を変更する

部分的に修飾された `relation` オブジェクト名を変更する

`relation alias` オブジェクト名を変更する

`function` オブジェクト名を変更する

`attribute` オブジェクト名を変更する

`attribute alias` オブジェクト名を変更する