針對批次翻譯找出對應的 SQL 物件名稱

物件名稱對應功能可讓您設定 JSON 規則，在批次 SQL 翻譯期間重新命名 SQL 物件 (例如資料庫、結構定義、資料表和資料欄)，以符合 BigQuery 命名慣例。

只有舊版 Batch API 支援使用 JSON 對應物件名稱。如果您使用 BigQuery Migration API，或從 Google Cloud 控制台啟動批次工作，請改用以 YAML 為基礎的物件名稱對應。

總覽

名稱對應功能可讓您找出來源檔案中的 SQL 物件名稱，並在 BigQuery 中為這些物件指定目標名稱。您可以使用下列部分或所有元件，為物件設定名稱對應：

  • 名稱對應規則，包含：
    • 來源名稱部分：提供來源系統中物件的完整名稱。
    • type：用於識別來源物件的類型。
    • 提供 BigQuery 物件名稱的目標名稱部分。
  • 「預設資料庫」名稱，用於未指定資料庫名稱的來源物件。
  • 預設結構定義名稱，用於未指定結構定義的來源物件。

名稱部分

您可以使用下列名稱部分的組合，在名稱對應規則中提供來源和目標物件名稱的值：

  • 資料庫：命名階層的頂層。來源平台可能會使用其他字詞，例如「專案」。
  • 結構定義：命名階層的第二層。來源平台可能會使用其他字詞，例如「資料集」。
  • 關係：命名階層的第三層。來源平台可能會使用其他字詞，例如「table」。
  • 屬性：命名階層的最低層級。來源平台可能會使用其他字詞，例如「欄」。

物件類型

您也必須在名稱對應規則中，指定要重新命名的來源物件類型。支援的物件類型如下：

  • Database：物件階層中的頂層物件，例如 database.schema.relation.attribute。來源平台可能會使用其他字詞，例如「專案」。將物件類型指定為 database，會變更 DDL 和 DML 陳述式中所有對來源字串的參照。
  • Schema：物件階層中的第二層物件。來源平台可能會使用其他字詞，例如「資料集」。如果將物件類型指定為 schema，DDL 和 DML 陳述式中所有參照來源字串的部分都會變更。
  • Relation：物件階層中的第三層物件。來源平台可能會使用其他字詞，例如「table」。將物件類型指定為 relation，會變更 DDL 陳述式中所有參照來源字串的部分。
  • Relation alias：第三層物件的別名。例如，在查詢 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：物件階層中的第四層物件。來源平台可能會使用其他字詞，例如「欄」。將物件類型指定為 attribute，會變更 DDL 陳述式中所有參照來源字串的部分。
  • Attribute alias：第四層物件的別名。舉例來說，在查詢 SELECT field1 FROM myTable; 中，field1 是屬性別名。將物件類型指定為 attribute alias，會變更 DML 陳述式中所有對來源字串的參照。

物件類型的必要名稱部分

如要在名稱對應規則中描述物件，請使用下表中為各物件類型識別的名稱部分：

類型 來源物件名稱 目標物件名稱
資料庫名稱部分 結構定義名稱部分 關係名稱部分 屬性名稱部分 資料庫名稱部分 結構定義名稱部分 關係名稱部分 屬性名稱部分
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 專案名稱附加至所有翻譯物件，最簡單的方法是在建立翻譯工作時指定預設資料庫名稱。這適用於使用三部分命名法的來源檔案，或使用四部分命名法但未指定最高層級物件名稱的來源檔案。

舉例來說，如果您指定預設資料庫名稱 myproject，則 SELECT * FROM database.table 等來源陳述式會轉譯為 SELECT * FROM myproject.database.table。如果物件已使用資料庫名稱部分 (例如 SELECT * FROM database.schema.table)，則必須使用名稱對應規則，將 database.schema.table 重新命名為 myproject.schema.table。

預設結構定義

如要完整限定來源檔案中所有未使用四部分命名的物件名稱，您可以在建立翻譯工作時，同時提供預設資料庫名稱和預設結構定義名稱。預設結構定義名稱會做為結構定義搜尋路徑選項中的第一個結構定義名稱。

舉例來說，如果您指定預設資料庫名稱 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 層級的其他物件都不會變更名稱。

系統會套用最明確的規則

一個物件只能套用一項名稱對應規則。如果有多項規則可能影響單一物件，系統會套用影響最低層級名稱部分的規則。舉例來說，如果 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。

處理沒有四部分名稱的來源物件

部分來源系統 (例如 Teradata) 會使用三個名稱部分，完整限定物件名稱。許多來源系統也允許您在 SQL 方言中使用部分限定名稱，例如使用 database1.schema1.table1、schema1.table1 和 table1 在不同情境中參照同一個物件。如果來源檔案包含未使用四部分物件名稱的物件，您可以搭配使用名稱對應和指定預設資料庫名稱和預設結構定義名稱，以達到所需的名稱對應。

如需使用名稱對應規則搭配預設資料庫名稱或預設結構定義名稱的範例，請參閱「針對名稱完整程度不同的物件，變更資料庫名稱部分」和「變更部分限定的關係物件名稱」。

名稱對應範例

請參閱本節中的範例，瞭解名稱對應規則在常見用途中的運作方式。

變更完整物件的資料庫名稱部分

以下範例會將所有具有完整名稱的 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 檔案格式

如果您選擇使用 JSON 檔案 (而非 Google Cloud 控制台) 指定名稱對應規則，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"
    }
  }]
}