更新檢視表屬性

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

所需權限

您至少必須擁有 bigquery.tables.updatebigquery.tables.get 權限,才能更新檢視表。如要更新檢視表的 SQL 查詢,還需擁有檢視表 SQL 查詢所參照的資料表查詢權限。

以下是包含 bigquery.tables.updatebigquery.tables.get 權限的預先定義 Cloud IAM 角色:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

此外,當具備 bigquery.datasets.create 權限的使用者建立資料集時,會獲得該資料集的 bigquery.dataOwner 存取權。bigquery.dataOwner 存取權可讓使用者更新資料集中的資料表和檢視表。

如要進一步瞭解 BigQuery 中的 Cloud IAM 角色和權限,請參閱預先定義的角色和權限

更新檢視表的 SQL 查詢

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

  • 使用 Cloud Console 或 BigQuery 傳統網頁版 UI
  • 使用指令列工具的 bq update 指令
  • 呼叫 tables.patch API 方法
  • 使用用戶端程式庫

您可以透過 CLI 或 API 將 SQL 方言從舊版 SQL 變更為標準 SQL,但無法使用 Cloud Console 或 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] (儲存檢視表)。

    更新檢視表

CLI

發出含有 --view 旗標的 bq update 指令。如要使用標準 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 查詢。mydatasetmyotherproject 中,而不是您的預設專案中。用於更新檢視表的查詢範例會查詢來自美國名稱資料公開資料集的資料。

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
    • Cloud Console 目前不支援修改檢視表的到期時間
  • 使用 CLI 的 bq update 指令
  • 呼叫 tables.patch API 方法
  • 使用用戶端程式庫

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

主控台

  1. 在導覽窗格中選取檢視表。

  2. 在「View Details」(檢視表詳細資料) 頁面上,按一下 [Details] (詳細資料) 分頁標籤。

  3. 在 [View info] (檢視表資訊) 右側,按一下編輯圖示 (鉛筆圖案)。

  4. 在 [View info] (檢視表資訊) 對話方塊的 [View expiration] (檢視表到期時間) 部分,點選 [Specify date] (指定日期)。

  5. 在日期選擇器中,輸入到期日期與時間,然後按一下 [Ok] (確定)

  6. 按一下 [Update] (更新)。已更新的到期時間會顯示在「View info」(檢視表資訊) 區段中。

DDL

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

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

如何在 Cloud Console 中使用 DDL 陳述式:

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

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

    ALTER VIEW mydataset.myview
    SET OPTIONS (
    -- Sets view expiration to timestamp 2025-02-03 12:34:56 in the America/Los Angeles time zone
    expiration_timestamp=TIMESTAMP("2025-02-03 12:34:56", "America/Los Angeles")
    );
    
  3. 按一下 [Run query] (執行查詢)

傳統版 UI

  1. 在導覽窗格中選取檢視表。

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

  3. 針對「Expiration Time」,按一下 [Edit]。

  4. 在「Update Expiration」(更新到期時間) 對話方塊中,按一下 [In] (資料表應於多久後到期),然後以天為單位輸入到期時間。

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

    檢視表到期時間

CLI

發出含有 --expiration 旗標的 bq update 指令。如果您要更新在預設專案以外的專案中的檢視表,請使用下列格式將專案 ID 新增至資料集名稱:project_id:dataset

bq update \
--expiration integer \
project_id:dataset.view

其中:

  • integer:資料表的預設生命週期 (以秒為單位), 最小值是 3600 秒 (1 小時)。到期時間為目前時間加整數值。
  • 「project_id」是您的專案 ID。
  • 「dataset」是您要更新的檢視表所屬的資料集。
  • 「view」是您要更新的檢視表名稱。

範例:

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

bq update --expiration 432000 mydataset.myview

輸入下列指令,以將 mydataset 中的 myview 到期時間更新為 5 天 (432000 秒)。mydatasetmyotherproject 中,而不是您的預設專案中。

bq update --expiration 432000 myotherproject:mydataset.myview

API

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

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
}

Node.js

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

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

async function updateTableExpiration() {
  // Updates a table's expiration.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset', // Existing dataset
  // const tableId = 'my_table', // Existing table
  // const expirationTime = Date.now() + 1000 * 60 * 60 * 24 * 5 // 5 days from current time in ms

  // Retreive current table metadata
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();

  // Set new table expiration to 5 days from current time
  metadata.expirationTime = expirationTime.toString();
  const [apiResponse] = await table.setMetadata(metadata);

  const newExpirationTime = apiResponse.expirationTime;
  console.log(`${tableId} expiration: ${newExpirationTime}`);
}

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

更新檢視表的說明

您可以透過以下方式更新檢視表的說明:

  • 使用 Cloud Console 或 BigQuery 傳統網頁版 UI
  • 使用 bq update CLI 指令
  • 呼叫 tables.patch API 方法
  • 使用用戶端程式庫

如何更新檢視表的說明:

主控台

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

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

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

    檢視詳細資訊

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

    編輯檢視表說明

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

DDL

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

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

如何在 Cloud Console 中使用 DDL 陳述式:

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

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

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

  3. 按一下 [Run query] (執行查詢)

傳統版 UI

  1. 在導覽窗格中選取檢視表。

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

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

  4. 在隨即顯示的方塊中輸入說明。當您按一下方塊以外的地方時,系統就會儲存您輸入的文字。

    資料表說明

CLI

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

bq update \
--description "description" \
project_id:dataset.view

其中:

  • 「description」是描述檢視表的文字 (以引號表示)。
  • 「project_id」是您的專案 ID。
  • 「dataset」是您要更新的檢視表所屬的資料集。
  • 「view」是您要更新的檢視表名稱。

範例:

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

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

輸入下列指令,將 mydataset 中的 myview 說明變更為 「Description of mydataset」(mydataset 的說明)。mydatasetmyotherproject 中,而不是您的預設專案中。

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);

Node.js

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

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

async function updateTableDescription() {
  // Updates a table's description.

  // Retreive current table metadata
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();

  // Set new table description
  const description = 'New table description.';
  metadata.description = description;
  const [apiResponse] = await table.setMetadata(metadata);
  const newDescription = apiResponse.description;

  console.log(`${tableId} description: ${newDescription}`);
}

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

後續步驟

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

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

這個網頁
需要協助嗎?請前往我們的支援網頁