管理資料表

這份文件說明如何在 BigQuery 中管理資料表。您可透過下列方式管理 BigQuery 資料表:

  • 更新資料表的:
    • 到期時間
    • 說明
    • 結構定義
    • 標籤
  • 重新命名 (複製) 資料表
  • 複製資料表
  • 刪除資料表
  • 還原已刪除的資料表

如需有關建立及使用資料表的詳細資訊,包括取得資料表資訊、列出資料表及控管資料表資料存取權等,請參閱建立與使用資料表一文。

更新資料表屬性

您可以更新資料表的:

所需權限

如要更新資料表屬性,您必須擁有資料集層級的 WRITER 存取權,或是取得具備 bigquery.tables.update 權限的專案層級身分與存取權管理 (IAM) 角色。以下是具備 bigquery.tables.update 權限的預先定義專案層級 IAM 角色:

此外,因為 bigquery.user 角色擁有 bigquery.datasets.create 權限,所以接受 bigquery.user 角色指派的使用者可以更新那位使用者在資料集中建立的任何資料表。當接受 bigquery.user 角色指派的使用者建立資料集時,那位使用者即被授予資料集的 OWNER 存取權。資料集的 OWNER 存取權可讓使用者完全控管該資料集,以及其中的所有資料表和檢視畫面。

如要深入瞭解 BigQuery 中的 IAM 角色和權限,請參閱:存取權控管

更新資料表的說明

您可以透過以上方式更新資料表的說明:

  • 使用 GCP 主控台或傳統 BigQuery 網頁版 UI
  • 使用 bq update CLI 指令
  • 呼叫 tables.patch API 方法

如要更新資料表的說明:

主控台

選項 1:手動變更說明

使用主控台 BigQuery 網頁版 UI 建立資料表時將無法新增說明。建立資料表後,您可以在「Details」(詳細資料) 頁面上新增說明。

  1. 在「Resources」(資源) 窗格中,選取資料表。

  2. 在「Query editor」(查詢編輯器) 的下方,按一下 [Details] (詳細資料)。

編輯資料表結構定義

  1. 在「Description」(說明) 區段中,按一下鉛筆圖示來編輯說明。

編輯說明

  1. 在方塊中輸入說明,然後按一下 [Update] (更新) 即可儲存。

選項 2:使用 DDL 陳述式

資料定義語言 (DDL) 陳述式可讓您使用標準 SQL 查詢語法建立和修改資料表和檢視表。

詳情請參閱使用資料定義語言陳述式一文。

  1. 按一下 [Compose new query] (撰寫新查詢)

  2. 將您的 DDL 陳述式輸入到「Query editor」(查詢編輯器) 的文字區域。

     #standardSQL
     ALTER TABLE mydataset.mytable
     SET OPTIONS (
       description="Description of mytable"
     )
     

傳統版 UI

選項 1:手動變更說明

  1. 在導覽窗格中,選取資料表。

  2. 在「Table Details」(資料表詳細資料) 頁面上,按一下 [Details] (詳細資料)

  3. 在「Description」(說明) 區段中,按一下 [Describe this table] 以開啟說明方塊。

  4. 在方塊中輸入說明。在方塊外部按一下後,系統就會儲存該文字。

    資料表說明

選項 2:使用 DDL 陳述式

資料定義語言 (DDL) 陳述式可讓您使用標準 SQL 查詢語法建立和修改資料表和檢視表。

詳情請參閱使用資料定義語言陳述式一文。

  1. 按一下 [Compose query] (撰寫查詢)

  2. 將您的 DDL 陳述式輸入到「New Query」(新查詢) 文字區域中。

     #standardSQL
     ALTER TABLE mydataset.mytable
     SET OPTIONS (
       description="Description of mytable"
     )
     

CLI

發出 bq update 指令並搭配使用 --description 標記。如果要更新非預設專案中的資料表,請使用下列格式將專案 ID 新增至資料集名稱: [PROJECT_ID]:[DATASET]

bq update --description "[DESCRIPTION]" [PROJECT_ID]:[DATASET].[TABLE]

其中:

  • [DESCRIPTION] 是在引號中說明資料表的文字。
  • [PROJECT_ID] 是您的專案 ID。
  • [DATASET] 是含有您要更新資料表的資料集名稱。
  • [TABLE] 是您要更新的資料表名稱。

範例:

輸入下列指令,將 mydataset 中的 mytable 的說明變更為「mytable 的說明」。mydataset 位於預設專案中。

bq update --description "Description of mytable" mydataset.mytable

輸入下列指令,將 mydataset 中的 mytable 說明變更為「mytable 的說明」。mydataset 位於 myotherproject 而非預設專案中。

bq update --description "Description of mytable" myotherproject:mydataset.mytable

API

呼叫 tables.patch 方法並使用資料表資源中的 description 屬性更新資料表說明。由於 tables.update 方法會取代整個資料表資源,因此建議使用 tables.patch 方法。

Go

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
tableRef := client.Dataset(datasetID).Table(tableID)
meta, err := tableRef.Metadata(ctx)
if err != nil {
	return err
}
update := bigquery.TableMetadataToUpdate{
	Description: "Updated description.",
}
if _, err = tableRef.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Java

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件

// String datasetName = "my_dataset_name";
// String tableName = "my_table_name";
// String newDescription = "new_description";

Table beforeTable = bigquery.getTable(datasetName, tableName);
TableInfo tableInfo = beforeTable.toBuilder()
    .setDescription(newDescription)
    .build();
Table afterTable = bigquery.update(tableInfo);

Python

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件

設定 Table.description 屬性並呼叫 Client.update_table(),將更新內容傳送到 API。

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.description == "Original description."
table.description = "Updated description."

table = client.update_table(table, ["description"])  # API request

assert table.description == "Updated description."

更新資料表的到期時間

您可以設定資料集層級的資料表預設到期時間,也可以在建立資料表時設定資料表的到期時間。資料表的到期時間通常稱為「存留時間」或 TTL。

如果您在建立資料表時設定了到期時間,會忽略資料集的預設資料表到期時間。如果您未設定資料集層級的資料表預設到期時間,且未在建立資料表時設定資料表到期時間,則資料表永遠不會過期,屆時您必須手動刪除資料表。

建立資料表後,您可以隨時透過以下方式更新資料表的到期時間:

  • 使用 GCP 主控台或傳統 BigQuery 網頁版 UI
  • 使用 CLI 的 bq update 指令
  • 呼叫 tables.patch API 方法

如要更新資料表的到期時間:

主控台

選項 1:手動變更到期時間

使用主控台 BigQuery 網頁版 UI 建立資料表時,您無法新增到期時間。建立資料表後,您可以在「Table Details」(資料表詳細資料) 頁面上新增或更新資料表的到期時間。

  1. 在「Resources」(資源) 窗格中,選取資料表。

  2. 在「Query editor」(查詢編輯器) 的下方,按一下 [Details] (詳細資料)。

  3. 按一下「Table info」(資料表資訊) 旁的鉛筆圖示。

  4. 針對「Table expiration」(資料表到期時間),選取 [Specify date] (指定日期)。然後使用日曆小工具選取到期日。

  5. 按一下 [Update] (更新) 即可儲存。已更新的到期時間會顯示在「Table info」(資料表資訊) 區段。

選項 2:使用 DDL 陳述式

資料定義語言 (DDL) 陳述式可讓您使用標準 SQL 查詢語法建立和修改資料表和檢視表。

詳情請參閱使用資料定義語言陳述式一文。

  1. 按一下 [Compose new query] (撰寫新查詢)

  2. 將您的 DDL 陳述式輸入到「Query editor」(查詢編輯器) 的文字區域。

     #standardSQL
     ALTER TABLE mydataset.mytable
     SET OPTIONS (
       -- Sets table expiration to timestamp 2025-02-03 12:34:56
       expiration_timestamp=TIMESTAMP "2025-02-03 12:34:56"
     )
     

傳統版 UI

選項 1:手動變更到期時間

  1. 在導覽窗格中,選取資料表。

  2. 在「Table Details」(資料表詳細資料) 頁面上,按一下 [Details] (詳細資料)

  3. 針對「Expiration Time」(到期時間),按一下 [Edit] (編輯)

  4. 在「Update Expiration」對話方塊中,按一下 [In],然後以天為單位輸入到期時間。

  5. 按一下 [OK] (確定)。已更新的到期時間會顯示在「Details」(詳細資料) 頁面上。

    資料表到期時間

選項 2:使用 DDL 陳述式

資料定義語言 (DDL) 陳述式可讓您使用標準 SQL 查詢語法建立和修改資料表和檢視表。

詳情請參閱使用資料定義語言陳述式一文。

  1. 按一下 [Compose query] (撰寫查詢)

  2. 將您的 DDL 陳述式輸入到「New Query」(新查詢) 文字區域中。

     #standardSQL
     ALTER TABLE mydataset.mytable
     SET OPTIONS (
       -- Sets table expiration to timestamp 2025-02-03 12:34:56
       expiration_timestamp=TIMESTAMP "2025-02-03 12:34:56"
     )
     

CLI

發出 bq update 指令並搭配使用 --expiration 標記。如果要更新非預設專案中的資料表,請使用下列格式將專案 ID 新增至資料集名稱: [PROJECT_ID]:[DATASET]

bq update --expiration [INTEGER] [PROJECT_ID]:[DATASET].[TABLE]

其中:

  • [INTEGER] 是資料表的預設生命週期 (以秒為單位)。最小值是 3600 秒 (1 小時)。到期時間為目前時間加整數值。
  • [PROJECT_ID] 是您的專案 ID。
  • [DATASET] 是含有您要更新資料表的資料集名稱。
  • [TABLE] 是您要更新的資料表名稱。

範例:

輸入下列指令,將 mydatasetmytable 的到期時間更新為 5 天 (432000 秒)。mydataset 位於預設專案中。

bq update --expiration 432000 mydataset.mytable

輸入下列指令,將 mydatasetmytable 的到期時間更新為 5 天 (432000 秒)。mydataset 位於 myotherproject 中,而非預設專案中。

bq update --expiration 432000 myotherproject:mydataset.mytable

API

呼叫 tables.patch 方法並使用資料表資源中的 expirationTime 屬性更新資料表的到期時間 (以毫秒為單位)。由於 tables.update 方法會取代整個資料表資源,因此建議使用 tables.patch 方法。

Go

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
tableRef := client.Dataset(datasetID).Table(tableID)
meta, err := tableRef.Metadata(ctx)
if err != nil {
	return err
}
update := bigquery.TableMetadataToUpdate{
	ExpirationTime: time.Now().Add(time.Duration(5*24) * time.Hour), // table expiration in 5 days.
}
if _, err = tableRef.Update(ctx, update, meta.ETag); err != nil {
	return err
}

Java

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件

Table beforeTable = bigquery.getTable(datasetName, tableName);

// Set table to expire 5 days from now.
long expirationMillis = DateTime.now().plusDays(5).getMillis();
TableInfo tableInfo = beforeTable.toBuilder()
        .setExpirationTime(expirationMillis)
        .build();
Table afterTable = bigquery.update(tableInfo);

Python

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件

設定 Table.expires 屬性並呼叫 Client.update_table(),將更新內容傳送到 API。

import datetime
import pytz

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('my_table')
# table = client.get_table(table_ref)  # API request

assert table.expires is None

# set table to expire 5 days from now
expiration = datetime.datetime.now(pytz.utc) + datetime.timedelta(days=5)
table.expires = expiration
table = client.update_table(table, ["expires"])  # API request

# expiration is stored in milliseconds
margin = datetime.timedelta(microseconds=1000)
assert expiration - margin <= table.expires <= expiration + margin

更新資料表的結構定義

如需更新資料表結構定義的操作說明,請參閱修改資料表結構定義

重新命名資料表

目前,您無法變更現有資料表的名稱。如果需要變更資料表名稱,請依複製資料表一節中的步驟操作。當您在複製操作中指定目的地資料表時,請使用新資料表名稱。

複製資料表

您可以透過以下方式複製資料表:

  • 使用 GCP 主控台或傳統 BigQuery 網頁版 UI
  • 使用指令列工具的 bq cp 指令
  • 呼叫 jobs.insert API 方法並設定複製工作

所需權限

如要在資料集層級複製資料表,您需要擁有該資料表所屬來源資料集的 READER 存取權,以及目的地資料集的 WRITER 存取權。

如果不使用資料集層級權限,您可以使用擁有 bigquery.tables.createbigquery.tables.getData 權限的專案層級 IAM 角色。您必須具有 bigquery.tables.create 權限才能在目的地資料集裡建立資料表副本,且必須具有 bigquery.tables.getData 權限才能在要複製的資料表中讀取資料。

下列預先定義的專案層級 IAM 角色擁有專案中每個資料集的 bigquery.tables.createbigquery.tables.getData 權限:

此外,因為 bigquery.user 角色擁有 bigquery.datasets.create 權限,所以接受 bigquery.user 角色指派的使用者就能讀取原始使用者建立的任何資料表資料,並且可在原始使用者建立的任何資料集建立資料表複本。當取得 bigquery.user 角色指派的使用者建立資料集時,該使用者即被授予該資料集的 OWNER 存取權。 資料集的 OWNER 存取權可讓使用者完全控管那個資料集以及其中的所有資料表。

如要深入瞭解 BigQuery 中的 IAM 角色和權限,請參閱存取權控管。如要深入瞭解資料集層級角色,則請參閱資料集的原始角色一節。

複製資料表的限制

資料表複製工作有下列限制:

  • 當您複製資料表時,目的地資料表的名稱必須遵循與您建立資料表時相同的命名慣例。
  • 資料表複製必須遵循 BigQuery 有關複製工作的配額政策
  • 當您使用 GCP 主控台或傳統 BigQuery 網頁版 UI 複製資料表時,您無法在目的地資料集覆寫現有資料表。目的地資料集裡的資料表名稱不得重複。
  • 複製資料表時,目的地資料集的所在位置必須與包含所複製資料表的資料集位置相同。例如,您無法將位於歐盟資料集的資料表複製並寫入到位於美國的資料集。
  • GCP 主控台或傳統 BigQuery 網頁版 UI 不支援將多個來源資料表複製到目的地資料表。
  • 使用 CLI 或 API 複製多個來源資料表到目的地資料表時,所有來源資料表都必須具有相同的結構定義。

複製單一來源資料表

您可以透過以下方式複製單一資料表:

  • 使用 GCP 主控台或傳統 BigQuery 網頁版 UI
  • 使用指令列工具的 bq cp 指令
  • 呼叫 jobs.insert API 方法、設定複製工作,並指定 sourceTable 屬性

無論使用的是 GCP 主控台或傳統 BigQuery 網頁版 UI,一項複製工作中只能有一個來源資料表與一個目的地資料表。您必須使用指令列工具或 API,才能將多個來源檔案複製到目的地資料表。

如要複製單一來源資料表:

主控台

  1. 選取您要從「Resources」(資源) 窗格中複製的資料表。在「Query editor」(查詢編輯器) 的下方,按一下 [Copy table] (複製資料表)

  2. 在「Destination」(目的地) 下方的「Copy table」(複製資料表) 對話方塊中:

    • 針對「Project name」(專案名稱),選擇將用來儲存複製資料表的專案。
    • 針對「Dataset name」(資料集名稱),選取您要用來儲存複製資料表的資料集。來源與目的地資料集必須位於相同的位置
    • 針對「Table name」(資料表名稱),輸入新資料表的名稱。目的地資料集的資料表名稱不得重複。資料表名稱不得超過 1024 個字元,並且只能包含 a-z、A-Z、0-9 或 _ (底線字元)。使用傳統 BigQuery 網頁版 UI 時,無法在目的地資料集裡覆寫現有資料表。
  3. 按一下 [Copy] (複製) 即可開始複製工作。

傳統版 UI

  1. 在您想要複製的資料表旁按一下「顯示選單」圖示 向下箭號,然後點選 [Copy Table] (複製資料表)。

  2. 在「Copy Table」(複製資料表) 對話方塊中:

    • 針對「Destination project」(目標專案),選擇將用來儲存複製資料表的專案。
    • 針對「Destination dataset」(目的地資料集),選取您要用來儲存複製資料表的資料集。來源與目的地資料集必須位於相同的位置
    • 針對「Destination table」(目的地表格),輸入新資料表的名稱。目的地資料集中的資料表名稱不得重複。資料表名稱不得超過 1024 個字元,並且只能包含 a-z、A-Z、0-9 或 _ (底線字元)。使用傳統 BigQuery 網頁版 UI 時,無法在目的地資料集中覆寫現有資料表。

      資料表複製

  3. 按一下 [OK] (確定) 即可開始複製工作。

指令列

發出 bq cp 指令。選用標記可用來控管目的地資料表的寫入配置:

  • -a--append_table 可將資料從來源資料表附加至目的地資料集的現有資料表。
  • -f--force 可覆寫目的地資料集裡的現有資料表,並且不會提示您確認。
  • 如果目的地資料集裡已有資料表,-n--no_clobber 會傳回下列錯誤訊息:Table '[PROJECT_ID]:[DATASET].[TABLE]' already exists, skipping。如未指定 -n,預設行為是提示您選擇是否取代目的地資料表。
  • --destination_kms_key 是客戶管理的 Cloud KMS 金鑰,可用來加密目的地資料表。

本文不示範 --destination_kms_key。請參閱使用 Cloud KMS 金鑰保護資料以取得詳細資訊。

如果來源或目的地資料集位於非預設專案中,請使用下列格式將專案 ID 新增至資料集名稱:[PROJECT_ID]:[DATASET]

提供 --location 標記,並將值設為您的位置

bq --location=[LOCATION] cp -a -f -n [PROJECT_ID]:[DATASET].[SOURCE_TABLE] [PROJECT_ID]:[DATASET].[DESTINATION_TABLE]

其中:

  • [LOCATION] 是您的位置名稱。--location 則為選用標記。舉例來說,如果您在東京地區使用 BigQuery,請將標記的值設為 asia-northeast1。您可以使用 .bigqueryrc 檔案設定位置的預設值。
  • [PROJECT_ID] 是您的專案 ID。
  • [DATASET] 是來源或目的地資料集的名稱。
  • [SOURCE_TABLE] 是您要複製的資料表。
  • [DESTINATION_TABLE] 是目的地資料集資料表的名稱。

範例:

輸入下列指令,將 mydataset.mytable 複製到 mydataset2.mytable2。 兩個資料集都在您的預設專案中,並且都在 US 多地區位置建立。

bq --location=US cp mydataset.mytable mydataset2.mytable2

輸入下列指令,複製 mydataset.mytable 並以相同名稱覆寫目的地資料表。來源資料集位於預設專案中。目的地資料集位於 myotherproject 中。-f 捷徑可用來在無提示的情況下覆寫目的地資料表。mydatasetmyotherdataset 都建立於 US 多地區位置。

bq --location=US cp -f mydataset.mytable myotherproject:myotherdataset.mytable

輸入下列指令,複製 mydataset.mytable,如果目的地資料集包含相同名稱的資料表,就傳回錯誤。來源資料集位於預設專案中。目的地資料集位於 myotherproject 中。-n 捷徑用於防止名稱相同的資料表遭到覆寫。兩個資料集都建立於 US 多地區位置。

bq --location=US cp -n mydataset.mytable myotherproject:myotherdataset.mytable

輸入下列指令,複製 mydataset.mytable 並以相同名稱將資料附加至目的地資料表。來源資料集位於預設專案中。目的地資料集位於 myotherproject 中。-a 捷徑可用來附加至目的地資料表。兩個資料集都建立於 US 多地區位置。

bq --location=US cp -a mydataset.mytable myotherproject:myotherdataset.mytable

輸入下列指令,將 mydataset.mytable 複製到 mydataset2.mytable2。 兩個資料集都位於預設專案中。兩個資料集都建立於 asia-northeast1 地區。

bq --location=asia-northeast1 cp mydataset.mytable mydataset2.mytable2

API

如要使用 API 複製資料表:

您可以呼叫 bigquery.jobs.insert 方法並設定 copy 工作,使用 API 複製現有資料表。在工作資源jobReference 區段中,於 location 屬性指定您的位置。

您必須在工作設定中指定下列值:

"copy": {
      "sourceTable": {       // Required
        "projectId": string, // Required
        "datasetId": string, // Required
        "tableId": string    // Required
      },
      "destinationTable": {  // Required
        "projectId": string, // Required
        "datasetId": string, // Required
        "tableId": string    // Required
      },
      "createDisposition": string,  // Optional
      "writeDisposition": string,   // Optional
    },

其中 sourceTable 會提供要複製的資料表相關資訊,destinationTable 會提供新資料表的相關資訊,createDisposition 會指定假如資料表不存在,是否新增資料表,而 writeDisposition 會指定是否覆蓋或附加到現有資料表。

C#

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 C# 設定說明進行操作。詳情請參閱 BigQuery C# API 參考說明文件

using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryCopyTable
{
    public void CopyTable(
        string projectId = "your-project-id",
        string destinationDatasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        TableReference sourceTableRef = new TableReference()
        {
            TableId = "shakespeare",
            DatasetId = "samples",
            ProjectId = "bigquery-public-data"
        };
        TableReference destinationTableRef = client.GetTableReference(
            destinationDatasetId, "destination_table");
        BigQueryJob job = client.CreateCopyJob(
            sourceTableRef, destinationTableRef)
            .PollUntilCompleted();  // Wait for the job to complete.
        // Retrieve destination table
        BigQueryTable destinationTable = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Copied {destinationTable.Resource.NumRows} rows from table "
            + $"{sourceTableRef.DatasetId}.{sourceTableRef.TableId} "
            + $"to {destinationTable.FullyQualifiedId}."
        );
    }
}

Go

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
dataset := client.Dataset(datasetID)
copier := dataset.Table(dstID).CopierFrom(dataset.Table(srcID))
copier.WriteDisposition = bigquery.WriteTruncate
job, err := copier.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}

Java

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件

TableId destinationId = TableId.of(dataset, tableName);
JobOption options = JobOption.fields(JobField.STATUS, JobField.USER_EMAIL);
Job job = table.copy(destinationId, options);
// Wait for the job to complete.
try {
  Job completedJob =
      job.waitFor(
          RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
          RetryOption.totalTimeout(Duration.ofMinutes(3)));
  if (completedJob != null && completedJob.getStatus().getError() == null) {
    // Job completed successfully.
  } else {
    // Handle error case.
  }
} catch (InterruptedException e) {
  // Handle interrupted wait
}

Node.js

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');

/**
 * TODO(developer): Uncomment the following lines before running the sample
 */
// const srcDatasetId = "my_src_dataset";
// const srcTableId = "my_src_table";
// const destDatasetId = "my_dest_dataset";
// const destTableId = "my_dest_table";

// Create a client
const bigqueryClient = new BigQuery();

async function copyTable() {
  // Copies src_dataset:src_table to dest_dataset:dest_table.

  // Copy the table contents into another table
  const [job] = await bigqueryClient
    .dataset(srcDatasetId)
    .table(srcTableId)
    .copy(bigqueryClient.dataset(destDatasetId).table(destTableId));

  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

copyTable();

PHP

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 PHP 設定說明進行操作。詳情請參閱 BigQuery PHP API 參考說明文件

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $sourceTableId   = 'The BigQuery table ID to copy from';
// $destinationTableId = 'The BigQuery table ID to copy to';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$sourceTable = $dataset->table($sourceTableId);
$destinationTable = $dataset->table($destinationTableId);
$copyConfig = $sourceTable->copy($destinationTable);
$job = $sourceTable->runJob($copyConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Table copied successfully' . PHP_EOL);
}

Python

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件

# from google.cloud import bigquery
# client = bigquery.Client()

source_dataset = client.dataset("samples", project="bigquery-public-data")
source_table_ref = source_dataset.table("shakespeare")

# dataset_id = 'my_dataset'
dest_table_ref = client.dataset(dataset_id).table("destination_table")

job = client.copy_table(
    source_table_ref,
    dest_table_ref,
    # Location must match that of the source and destination tables.
    location="US",
)  # API request

job.result()  # Waits for job to complete.

assert job.state == "DONE"
dest_table = client.get_table(dest_table_ref)  # API request
assert dest_table.num_rows > 0

複製多個來源資料表

您可以透過以下方式將多個來源資料表複製到目的地資料表:

  • 使用指令列工具的 bq cp 指令
  • 呼叫 jobs.insert 方法、設定複製工作,並指定 sourceTables 屬性

所有來源資料表都必須擁有相同的結構定義,並且只允許有一個目的地資料表。

來源資料表必須指定為逗號分隔的清單。複製多個來源資料表時不可使用萬用字元。

複製多個來源資料表:

指令列

發出 bq cp 指令並以逗號分隔清單的形式包含多個來源資料表。 選用標記可用來控管目的地資料表的寫入配置:

  • -a--append_table 可將資料從來源資料表附加至目的地資料集的現有資料表。
  • -f--force 會覆寫目的地資料集的現有目的地資料表,並且不會提示您確認。
  • 如果目的地資料集裡已有資料表,-n--no_clobber 會傳回下列錯誤訊息:Table '[PROJECT_ID]:[DATASET].[TABLE]' already exists, skipping。如未指定 -n,預設行為是提示您選擇是否取代目的地資料表。
  • --destination_kms_key 是客戶管理的 Cloud KMS 金鑰,可用來加密目的地資料表。

本文不示範 --destination_kms_key。請參閱使用 Cloud KMS 金鑰保護資料以取得詳細資訊。

如果來源或目的地資料集位於非預設專案中,請使用下列格式將專案 ID 新增至資料集名稱:[PROJECT_ID]:[DATASET]

提供 --location 標記,並將值設為您的位置

bq --location=[LOCATION] cp -a -f -n [PROJECT_ID]:[DATASET].[SOURCE_TABLE],[PROJECT_ID]:[DATASET].[SOURCE_TABLE] [PROJECT_ID]:[DATASET].[DESTINATION_TABLE]

其中:

  • [LOCATION] 是您的位置名稱。--location 則為選用標記。舉例來說,如果您在東京地區使用 BigQuery,請將標記的值設為 asia-northeast1。您可以使用 .bigqueryrc 檔案設定位置的預設值。
  • [PROJECT_ID] 是您的專案 ID。
  • [DATASET] 是來源或目的地資料集的名稱。
  • [SOURCE_TABLE] 是您要複製的資料表。
  • [DESTINATION_TABLE] 是目的地資料集資料表的名稱。

範例:

輸入下列指令,將 mydataset.mytablemydataset.mytable2 複製到 mydataset2.tablecopy。 所有資料集都在您的預設專案中,並且都建立於 US 多地區位置。

bq --location=US cp mydataset.mytable,mydataset.mytable2 mydataset2.tablecopy

輸入下列指令,將 mydataset.mytablemydataset.mytable2 複製到 myotherdataset.mytable 並覆寫名稱相同的目的地資料表。目的地資料集位於 myotherproject 而非預設專案中。-f 捷徑可用來在無提示的情況下覆寫目的地資料表。兩個資料集都建立於 US 多地區位置。

bq --location=US cp -f mydataset.mytable,mydataset.mytable2 myotherproject:myotherdataset.mytable

輸入下列指令,複製 myproject:mydataset.mytablemyproject:mydataset.mytable2,如果目的地資料集中包含相同名稱的資料表,就傳回錯誤。目的地資料集位於 myotherproject 中。-n 捷徑用於防止名稱相同的資料表遭到覆寫。所有資料集都建立於 US 多地區位置。

bq --location=US cp -n myproject:mydataset.mytable,myproject:mydataset.mytable2 myotherproject:myotherdataset.mytable

輸入下列指令,複製 mydataset.mytablemydataset.mytable2 並以相同名稱將資料附加至目的地資料表。來源資料集位於預設專案中。目的地資料集位於 myotherproject 中。-a 捷徑可用來附加至目的地資料表。所有資料集都建立於 US 多地區位置。

bq --location=US cp -a mydataset.mytable,mydataset.mytable2 myotherproject:myotherdataset.mytable

輸入下列指令,將 mydataset.mytablemydataset.mytable2 複製到 mydataset2.tablecopy。 所有資料集都在您的預設專案中,並且都建立於 asia-northeast1 地區。

bq --location=asia-northeast1 cp mydataset.mytable,mydataset.mytable2 mydataset2.tablecopy

API

如要使用 API 複製多個資料表,請呼叫 jobs.insert 方法、設定複製工作,並指定 sourceTables 屬性。

工作資源jobReference 區段中,於 location 屬性指定您的地區。

Go

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
dataset := client.Dataset(datasetID)

srcTableIDs := []string{"table1", "table2"}
var tableRefs []*bigquery.Table
for _, v := range srcTableIDs {
	tableRefs = append(tableRefs, dataset.Table(v))
}
copier := dataset.Table(dstTableID).CopierFrom(tableRefs...)
copier.WriteDisposition = bigquery.WriteTruncate
job, err := copier.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}

Java

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件

TableId destinationTable = TableId.of(datasetId, destinationTableId);
CopyJobConfiguration configuration =
    CopyJobConfiguration.newBuilder(
        destinationTable,
        Arrays.asList(
            TableId.of(datasetId, "table1"),
            TableId.of(datasetId, "table2")))
    .build();

// Copy the tables.
Job job = bigquery.create(JobInfo.of(configuration));
job = job.waitFor();

// Check the table
StandardTableDefinition table = bigquery.getTable(destinationTable).getDefinition();
System.out.println("State: " + job.getStatus().getState());
System.out.printf("Copied %d rows.\n", table.getNumRows());

Python

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件

# from google.cloud import bigquery
# client = bigquery.Client()
# source_dataset_id = 'my_source_dataset'
# dest_dataset_id = 'my_destination_dataset'

table1_ref = client.dataset(source_dataset_id).table("table1")
table2_ref = client.dataset(source_dataset_id).table("table2")
dest_table_ref = client.dataset(dest_dataset_id).table("destination_table")

job = client.copy_table(
    [table1_ref, table2_ref],
    dest_table_ref,
    # Location must match that of the source and destination tables.
    location="US",
)  # API request
job.result()  # Waits for job to complete.

assert job.state == "DONE"
dest_table = client.get_table(dest_table_ref)  # API request
assert dest_table.num_rows > 0

刪除資料表

您可以透過以下方式刪除資料表:

  • 使用 GCP 主控台或傳統 BigQuery 網頁版 UI
  • 使用指令列工具的 bq rm 指令
  • 呼叫 tables.delete API 方法

目前,您一次只能刪除一個資料表。

刪除資料表時,也會刪除資料表中的所有資料。如要在指定時段過後自動刪除資料表,請設定資料集的預設資料表到期時間,或者在建立資料表時設定到期時間。

所需權限

如要刪除資料表,您必須具備資料集層級的 OWNER 存取權,或取得具備 bigquery.tables.delete 權限的專案層級 IAM 角色。以下是擁有 bigquery.tables.delete 權限的預先定義專案層級 IAM 角色:

取得預先定義專案層級角色指派的使用者可以刪除專案內任何資料集中的資料表。在資料集層級取得 OWNER 權限指派的使用者只能刪除那個資料集中的資料表。

此外,因為 bigquery.user 角色具備 bigquery.datasets.create 權限,所以取得 bigquery.user 角色指派的使用者可以在那位使用者建立的任何資料集中刪除資料表。當接受 bigquery.user 角色指派的使用者建立資料集時,那位使用者即被授予資料集的 OWNER 存取權。資料集的 OWNER 存取權可讓使用者完全控管該資料集,以及其中的所有資料表。

如要深入瞭解 BigQuery 中的 IAM 角色和權限,請參閱存取權控管。如要深入瞭解資料集層級角色,則請參閱資料集的原始角色一節。

刪除資料表

如要刪除資料表:

主控台

  1. 從「Resources」(資源) 窗格中選取資料表。在「Query editor」(查詢編輯器) 的下方,按一下 [Delete table] (刪除資料表)
  2. 在對話方塊中輸入資料表名稱,然後按一下 [Delete] (刪除) 確認操作。

傳統版 UI

  1. 在導覽列中,按一下資料表名稱旁的向下箭頭圖示 向下箭號圖示,然後點選 [Delete table] (刪除資料表)。

  2. 系統提示時,按一下 [OK] (確定) 確認操作。

指令列

使用 bq rm 指令並搭配使用 --table 標記 (或 -t 捷徑) 以刪除資料表。當您使用 CLI 移除資料表時,必須確認操作。您可以使用 --force 標記 (或 -f 捷徑) 來略過確認程序。

如果資料表位於預設專案以外的專案的資料集中,請使用下列格式將專案 ID 新增至資料集名稱: [PROJECT_ID]:[DATASET]

bq rm -f -t [PROJECT_ID]:[DATASET].[TABLE]

其中:

  • [PROJECT_ID] 是您的專案 ID。
  • [DATASET] 是包含該資料表之資料集的名稱。
  • [TABLE] 是您正在刪除之資料表的名稱。

範例:

輸入下列指令,從 mydataset 刪除 mytablemydataset 位於預設專案中。

bq rm -t mydataset.mytable

輸入下列指令,從 mydataset 刪除 mytablemydataset 位於 myotherproject 而非預設專案中。

bq rm -t myotherproject:mydataset.mytable

輸入下列指令,從 mydataset 刪除 mytablemydataset 位於預設專案中。這個指令使用 -f 捷徑略過確認程序。

bq rm -f -t mydataset.mytable

API

呼叫 tables.delete API 方法並使用 tableId 參數指定要刪除的資料表。

C#

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 C# 設定說明進行操作。詳情請參閱 BigQuery C# API 參考說明文件

using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryDeleteTable
{
    public void DeleteTable(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        client.DeleteTable(datasetId, tableId);
        Console.WriteLine($"Table {tableId} deleted.");
    }
}

Go

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
table := client.Dataset(datasetID).Table(tableID)
if err := table.Delete(ctx); err != nil {
	return err
}

Java

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件

TableId tableId = TableId.of(projectId, datasetName, tableName);
boolean deleted = bigquery.delete(tableId);
if (deleted) {
  // the table was deleted
} else {
  // the table was not found
}

Node.js

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');

async function deleteTable() {
  // Deletes "my_table" from "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  // Create a client
  const bigqueryClient = new BigQuery();

  // Delete the table
  await bigqueryClient
    .dataset(datasetId)
    .table(tableId)
    .delete();

  console.log(`Table ${tableId} deleted.`);
}
deleteTable();

PHP

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 PHP 設定說明進行操作。詳情請參閱 BigQuery PHP API 參考說明文件

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableId = 'The BigQuery table ID';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
$table->delete();
printf('Deleted table %s.%s' . PHP_EOL, $datasetId, $tableId);

Python

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件

from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to fetch.
# table_id = 'your-project.your_dataset.your_table'

# If the table does not exist, delete_table raises
# google.api_core.exceptions.NotFound unless not_found_ok is True
client.delete_table(table_id, not_found_ok=True)
print("Deleted table '{}'.".format(table_id))

Ruby

在試行此示例之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Ruby 設定說明進行操作。詳情請參閱 BigQuery Ruby API 參考說明文件

require "google/cloud/bigquery"

def delete_table dataset_id = "my_dataset_id", table_id = "my_table_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table    = dataset.table table_id

  table.delete

  puts "Table #{table_id} deleted."
end

還原已刪除的資料表

您可以還原在 2 天之內刪除的資料表。只要使用快照修飾符功能,就可以參照刪除事件發生前的資料表,然後複製這個資料表。但以這種形式建立參照,需要注意兩項要點:

  • 如果在刪除事件後,在資料集中建立了使用相同 ID 的資料表,則您無法參照已刪除的資料表。

  • 如果在資料表刪除事件後,還刪除/重建了封裝資料集,則您無法參照已刪除的資料表。

CLI

如要使用舊版 SQL 取消刪除資料表,請使用 @<time> 快照修飾符。首先,請確定資料表存在時間的 UNIX 時間戳記 (以毫秒為單位)。然後,將這個時間戳記的資料表複製到新資料表。新資料表的名稱必須與刪除的資料表名稱不同。

例如,輸入下列指令,將時間為 1418864998000mydataset.mytable 複製到新資料表 mydataset.newtable

提供 --location 標記,並將值設為您的位置

bq --location=[LOCATION] cp mydataset.mytable@1418864998000 mydataset.newtable

如需詳細資訊,請參閱舊版 SQL 中的資料表修飾符一文。

Go

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")

ds := client.Dataset(datasetID)
if _, err := ds.Table(tableID).Metadata(ctx); err != nil {
	return err
}
// Record the current time.  We'll use this as the snapshot time
// for recovering the table.
snapTime := time.Now()

// "Accidentally" delete the table.
if err := client.Dataset(datasetID).Table(tableID).Delete(ctx); err != nil {
	return err
}

// Construct the restore-from tableID using a snapshot decorator.
snapshotTableID := fmt.Sprintf("%s@%d", tableID, snapTime.UnixNano()/1e6)
// Choose a new table ID for the recovered table data.
recoverTableID := fmt.Sprintf("%s_recovered", tableID)

// Construct and run a copy job.
copier := ds.Table(recoverTableID).CopierFrom(ds.Table(snapshotTableID))
copier.WriteDisposition = bigquery.WriteTruncate
job, err := copier.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}

Java

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件

// String datasetId = "my_dataset";
String tableId = "oops_undelete_me";

// Record the current time.  We'll use this as the snapshot time
// for recovering the table.
long snapTime = Instant.now().getMillis();

// "Accidentally" delete the table.
bigquery.delete(TableId.of(datasetId, tableId));

// Construct the restore-from tableID using a snapshot decorator.
String snapshotTableId = String.format("%s@%d", tableId, snapTime);
// Choose a new table ID for the recovered table data.
String recoverTableId = String.format("%s_recovered", tableId);

// Construct and run a copy job.
CopyJobConfiguration configuration =
    CopyJobConfiguration.newBuilder(
        TableId.of(datasetId, recoverTableId),
        TableId.of(datasetId, snapshotTableId))
    .build();
Job job = bigquery.create(JobInfo.of(configuration));
job = job.waitFor();

// Check the table
StandardTableDefinition table = bigquery.getTable(
        TableId.of(datasetId, recoverTableId)).getDefinition();
System.out.println("State: " + job.getStatus().getState());
System.out.printf("Recovered %d rows.\n", table.getNumRows());

Python

在試用這個範例程式之前,請前往 BigQuery 快速入門導覽課程:使用用戶端程式庫頁面,按照 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件

# TODO(developer): Uncomment the lines below and replace with your values.
# import time
# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'  # Replace with your dataset ID.
# table_id = 'my_table'      # Replace with your table ID.

table_ref = client.dataset(dataset_id).table(table_id)

# TODO(developer): Choose an appropriate snapshot point as epoch
# milliseconds. For this example, we choose the current time as we're about
# to delete the table immediately afterwards.
snapshot_epoch = int(time.time() * 1000)

# "Accidentally" delete the table.
client.delete_table(table_ref)  # API request

# Construct the restore-from table ID using a snapshot decorator.
snapshot_table_id = "{}@{}".format(table_id, snapshot_epoch)
source_table_ref = client.dataset(dataset_id).table(snapshot_table_id)

# Choose a new table ID for the recovered table data.
recovered_table_id = "{}_recovered".format(table_id)
dest_table_ref = client.dataset(dataset_id).table(recovered_table_id)

# Construct and run a copy job.
job = client.copy_table(
    source_table_ref,
    dest_table_ref,
    # Location must match that of the source and destination tables.
    location="US",
)  # API request

job.result()  # Waits for job to complete.

print(
    "Copied data from deleted table {} to {}".format(table_id, recovered_table_id)
)

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁