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

プレビュー

このプロダクトには、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 一般提供前のプロダクトは「現状のまま」ご利用いただけますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

注: JSON を使用したオブジェクト名のマッピングは、以前のバッチ API でのみサポートされています。BigQuery Migration API を使用している場合や、Google Cloud コンソールからバッチジョブを開始する場合は、代わりに YAML ベースのオブジェクト名マッピングを使用します。

このドキュメントでは、バッチ変換中に 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"
    }
  }]
}