更新資料檢視屬性

本文說明如何在 BigQuery 中更新資料檢視屬性。建立資料檢視後,您可以更新下列資料檢視屬性:

必要權限

更新資料檢視需要與更新資料表相同的權限;也就是說,您必須具備資料集層級的 WRITER 存取權,或是取得具有 bigquery.tables.update 權限的專案層級身分與存取權管理角色。以下是包含 bigquery.tables.update 權限的預先定義專案層級身分與存取權管理角色:

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

如要深入瞭解 BigQuery 中的身分與存取權管理角色和權限,請參閱存取權控管一文。

更新資料檢視的 SQL 查詢

您可以透過以下方式更新用來定義資料檢視的 SQL 查詢:

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

您可以使用 CLI 或 API,將 SQL 方言從舊版 SQL 變更為標準 SQL,但無法使用 GCP 主控台或傳統 BigQuery 網頁版 UI,將舊版 SQL 資料檢視更新為標準 SQL。

如何更新資料檢視的 SQL 查詢:

主控台

  1. 在「Resources」(資源) 面板中選取資料檢視。

  2. 按一下 [Details] (詳細資料) 分頁標籤。

    瞭解詳情

  3. 在「Query」(查詢) 方塊上方,按一下 [Edit Query] (編輯查詢) 按鈕。接著在隨即顯示的對話方塊中按一下 [Open] (開啟)。

    編輯查詢

  4. 在「Query editor」(查詢編輯器) 方塊中編輯 SQL 查詢,然後按一下 [Save view] (儲存資料檢視)。

    儲存資料檢視

  5. 確定「Save view」(儲存資料檢視) 對話方塊中的所有欄位都正確無誤,再點選 [Save] (儲存)。

傳統版 UI

  1. 選取資料檢視。

  2. 在「View Details」面板中,按一下 [Details]

  3. 在「Query」方塊下方,按一下 [Edit Query]

  4. 在「Query」方塊中編輯 SQL 查詢,然後按一下 [Save View]

    更新資料檢視

指令列

發出 bq update 指令並搭配使用 --view 標記。如要使用標準 SQL,或將查詢方言從舊版 SQL 更新為標準 SQL,請加上 --use_legacy_sql 標記,並將其設定為 false

如果您的查詢參考儲存在 Google Cloud Storage 或本機檔案中的外部使用者定義的函式資源,請使用 --view_udf_resource 標記來指定這些資源。本文不示範 --view_udf_resource 標記。如要深入瞭解如何使用 UDF,請參閱 標準 SQL 使用者定義的函式

如果您要更新在預設專案以外的專案中的視圖,請使用下列格式將專案 ID 新增至資料集名稱: [PROJECT_ID]:[DATASET]

bq update --use_legacy_sql=false --view_udf_resource=[PATH_TO_FILE] --view='[QUERY]' [PROJECT_ID]:[DATASET].[VIEW]

其中:

  • [PATH_TO_FILE] 是程式碼檔案的 URI 或本機檔案系統路徑,該程式碼檔案會做為資料檢視使用的使用者定義函式資源立即載入和評估。請重複該標記以指定多個檔案。
  • [QUERY] 是一個有效的標準 SQL 查詢。
  • [PROJECT_ID] 是您的專案 ID。
  • [DATASET] 是包含視圖的資料集。
  • [VIEW] 是您要更新之視圖的名稱。

範例:

輸入下列指令,更新 mydataset 中名為 myview 之視圖的 SQL 查詢。mydataset 位於預設專案中。用於更新視圖的查詢範例會查詢來自 美國名稱資料 公開資料集的資料。

bq update --use_legacy_sql=false --view 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC' mydataset.myview

輸入下列指令,更新 mydataset 中名為 myview 之視圖的 SQL 查詢。mydataset 是在 myotherproject 而非預設專案中。用於更新視圖的查詢範例會查詢來自 美國名稱資料公開資料集的資料。

bq update --use_legacy_sql=false --view 'SELECT name,number FROM `bigquery-public-data.usa_names.usa_1910_current` WHERE gender = "M" ORDER BY number DESC' myotherproject:mydataset.myview

API

您可以使用含有已更新 view 屬性的資料表資源,透過呼叫 tables.patch 方法來更新資料檢視。由於 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")
view := client.Dataset(datasetID).Table(viewID)
meta, err := view.Metadata(ctx)
if err != nil {
	return err
}

newMeta := bigquery.TableMetadataToUpdate{
	// This example updates a view into the shakespeare dataset to exclude works named after kings.
	ViewQuery: "SELECT word, word_count, corpus, corpus_date FROM `bigquery-public-data.samples.shakespeare` WHERE corpus NOT LIKE '%king%'",
}

if _, err := view.Update(ctx, newMeta, meta.ETag); err != nil {
	return err
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# project = 'my-project'
# source_dataset_id = 'my_source_dataset'
# source_table_id = 'us_states'
# shared_dataset_ref = client.dataset('my_shared_dataset')

# This example shows how to update a shared view of a source table of
# US States. The view's query will be updated to contain only states with
# names starting with 'M'.
view_ref = shared_dataset_ref.table("my_shared_view")
view = bigquery.Table(view_ref)
sql_template = 'SELECT name, post_abbr FROM `{}.{}.{}` WHERE name LIKE "M%"'
view.view_query = sql_template.format(project, source_dataset_id, source_table_id)
view = client.update_table(view, ["view_query"])  # API request

更新資料檢視的到期時間

您可以設定資料集層級 (會同時影響資料表和視圖) 的資料表預設到期時間,也可以在建立視圖時設定視圖的到期時間。如果您在建立視圖時設定到期時間,系統將會忽略資料集的資料表預設到期時間。如果您未設定資料集層級的資料表預設到期時間,且未在建立資料檢視時設定到期時間,則資料檢視永遠不會過期,屆時您必須手動刪除資料檢視。

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

  • 使用傳統 BigQuery 網頁版 UI
    • GCP 主控台目前不支援修改資料檢視到期時間
  • 使用 CLI 的 bq update 指令
  • 呼叫 tables.patch API 方法。

當您更新資料檢視的到期時間時,必須根據資料檢視的建立時間計算到期時間。例如,如果視圖是在 2018 年 1 月 3 日建立的,而今天是 1 月 5 日,如果您使用 BigQuery 網路 UI 將到期時間設定為 1 天,則系統會將到期時間視為「已過去」,並立即刪除該視圖。

如何更新資料檢視的到期時間:

主控台

您無法透過主控台網頁版 UI 新增或更新資料檢視的到期時間。

傳統版 UI

選項 1:手動編輯到期時間

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

  2. 在「View 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 VIEW mydataset.myview
     SET OPTIONS (
       -- Sets view expiration to timestamp 2025-02-03 12:34:56
       expiration_timestamp=TIMESTAMP "2025-02-03 12:34:56"
     );
     

指令列

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

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

其中:

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

範例:

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

bq update --expiration 432000 mydataset.myview

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

bq update --expiration 432000 myotherproject:mydataset.myview

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
}

Python

更新資料檢視到期時間的程序與更新資料表到期時間的程序相同。

在嘗試這個範例之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Python 設定說明進行操作。詳情請參閱 BigQuery Python 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 update CLI 指令
  • 呼叫 tables.patch API 方法

如何更新資料檢視的說明:

主控台

使用 BigQuery 網頁版 UI 建立資料檢視時,您無法新增資料檢視的說明。資料檢視建立完成後,您可以在「Details」(詳細資料) 頁面上新增資料檢視的說明。

  1. 在「Resources」(資源) 清單中,選取資料檢視。

  2. 按一下 [Details] (詳細資料) 分頁標籤。

瞭解詳情

  1. 按一下「Description」(說明) 旁邊的鉛筆圖示。

編輯資料檢視說明

  1. 在隨即顯示的對話方塊中輸入說明。按一下 [Update] (更新),儲存新的說明。

傳統版 UI

選項 1:手動變更說明

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

  2. 在「View Details」頁面上,按一下 [Details]

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

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

    資料表說明

選項 2:使用 DDL 陳述式

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

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

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

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

     #standardSQL
     ALTER VIEW mydataset.myview
     SET OPTIONS (
       description="Description of myview"
     );
     

指令列

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

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

其中:

  • [DESCRIPTION] 是括號中之視圖的說明文字。
  • [PROJECT_ID] 是您的專案 ID。
  • [DATASET] 是包含您要更新之資料檢視的資料集名稱。
  • [VIEW] 是您要更新之資料檢視的名稱。

範例:

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

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

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

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

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 參考說明文件

# 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."

後續步驟

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

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

這個網頁