變更資料表

您可以使用 Lakehouse 執行階段目錄,修改 Apache Iceberg 資料表來演進結構定義 (例如新增資料欄),以及設定資料表屬性。這些更新可協助您儲存自訂中繼資料,或選擇加入 BigQuery 代管功能 (預先發布版),包括 BigQuery data manipulation language (DML) 和自動資料表維護。

您可以使用 Google Cloud 控制台、Apache Spark、Trino、BigQuery (預先發布版) 或 REST API 更改資料表。如要透過指令列更新資料表屬性,也可以使用 Google Cloud CLI。

事前準備

  1. 確認 Google Cloud 專案已啟用計費功能。

  2. 如果尚未啟用 BigLake API,請先啟用。

    啟用 API 所需的角色

    如要啟用 API,您必須具備 serviceusage.services.enable 權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    啟用 API

  3. 使用 Apache Iceberg REST 目錄端點設定 Lakehouse 執行階段目錄。

必要的角色

如要取得修改資料表所需的權限,請要求管理員在專案和 Storage bucket 中,授予您下列 IAM 角色:

  • 在憑證販售模式中變更資料表:BigLake 編輯者 (roles/biglake.editor) - 專案
  • 在非憑證臨時配發模式中變更資料表:
    • BigLake 編輯者 (roles/biglake.editor) - 專案
    • Storage 物件使用者 (roles/storage.objectUser) - Cloud Storage bucket

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色,取得必要權限。

表格功能和支援

使用 Lakehouse 執行階段目錄中的資料表時,建議您瞭解不同的資料表類型和選擇加入功能。如要進一步瞭解如何使用 Apache Iceberg 資料表,請參閱「Apache Iceberg 資料表總覽」。

支援的 Iceberg 資料表

僅支援 Apache Iceberg V2 (正式發布版) 和 V3 (預先發布版) 資料表。不支援 Iceberg V1 資料表。如要升級現有的 V1 資料表,請參閱「將 Iceberg V1 資料表升級至 V2」。

使用表格選項 (預先發布版)

您可以設定特定資料表屬性,選擇使用 BigQuery 代管功能,例如 BigQuery 資料操縱語言 (DML) 和自動資料表管理。啟用這些功能的方式,取決於資料表的建立位置:

  • 從 BigQuery:BigQuery DML 和自動資料表管理功能預設為啟用。
  • 開放原始碼引擎:如要選擇加入,必須明確設定資料表屬性。詳情請參閱「設定表格選項」。

如需詳細操作說明,請參閱「設定表格選項」。

變更資料表

選取下列選項之一:

控制台

  1. 前往 Google Cloud 控制台的「Lakehouse」Lakehouse頁面。

    前往 Lakehouse

  2. 選取現有目錄,如果沒有,請建立一個。

  3. 選取現有的命名空間,如果沒有,請建立一個。

  4. 在「Namespace details」(命名空間詳細資料) 頁面的「Tables」(資料表) 分頁中,按一下要修改的資料表名稱。「Table details」(資料表詳細資料) 頁面隨即開啟。

  5. 如要在資料表結構定義中新增資料欄,請按照下列步驟操作:

    1. 按一下「結構定義」分頁標籤。
    2. 點選「編輯結構定義」。
    3. 在「New fields」(新欄位) 部分,按一下「Add field」(新增欄位)。在「Field name」(欄位名稱) 中輸入資料欄名稱,然後在「Type」(類型) 清單中選取資料類型。如要改為以文字形式輸入欄位,請將「Edit as text」(以文字形式編輯) 切換鈕設為開啟,然後輸入 JSON 或以半形逗號分隔的 name:type 配對。
    4. 按一下「儲存」。
  6. 如要更新表格屬性,請按照下列步驟操作:

    1. 點按「Details」(詳細資料) 分頁標籤。
    2. 按一下「編輯詳細資訊」。
    3. 在「Properties」(屬性) 部分,更新現有屬性值。如要新增自訂屬性,請按一下「Add property」(新增屬性),然後在「Key」(鍵) 和「Value」(值) 欄位中輸入屬性鍵和值。

      舉例來說,如要啟用 BigQuery DML 或自動資料表維護功能,請在 gcp.biglake.bigquery-dml.enabled 或 gcp.biglake.table-management.enabled 的「Value」(值) 欄位中輸入 true。詳情請參閱「設定資料表選項」。

    4. 按一下「Update」。

Spark

spark.sql("ALTER TABLE TABLE_NAME ADD COLUMNS ( desc string);")
spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

如要啟用讀取/寫入互通性和資料表維護,請使用 SET TBLPROPERTIES 子句設定屬性:

SET TBLPROPERTIES (
  'gcp.biglake.bigquery-dml.enabled' = true,
  'gcp.biglake.table-management.enabled' = true
)

Trino

ALTER TABLE TABLE_NAME ADD COLUMN desc varchar;
DESCRIBE SCHEMA_NAME.TABLE_NAME;

如要啟用讀取/寫入互通性和資料表維護,您可以設定下列資料表屬性:

  • 'gcp.biglake.bigquery-dml.enabled' = true
  • 'gcp.biglake.table-management.enabled' = true

gcloud

如要使用 gcloud 更新資料表屬性,請執行 gcloud biglake iceberg tables update 指令。

gcloud biglake iceberg tables update TABLE_NAME \
    --project="PROJECT_ID" \
    --catalog="CATALOG_ID" \
    --namespace="NAMESPACE_NAME" \
    --update-properties="KEY=VALUE,..."

更改下列內容:

  • TABLE_NAME:Iceberg 資料表名稱。
  • PROJECT_ID:您的 Google Cloud專案 ID。
  • CATALOG_ID:目錄 ID。
  • NAMESPACE_NAME:目錄命名空間的名稱。
  • KEY=VALUE,...:要新增或更新的資料表屬性。

BigQuery

如要從 BigQuery 更新 Lakehouse 執行階段目錄中 Apache Iceberg 資料表的資料表屬性 (例如啟用 BigQuery DML 或自動資料表維護),請使用下列 GoogleSQL ALTER TABLE 陳述式:

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "enabled");

如要更新結構定義,並在 Lakehouse 執行階段目錄的 Apache Iceberg 資料表中新增資料欄,請使用下列 GoogleSQL ALTER TABLE 陳述式:

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
ADD COLUMN new_column STRING;

更改下列內容:

  • PROJECT_ID:您的 Google Cloud專案 ID。
  • CATALOG_ID:Lakehouse 執行階段目錄的 ID。
  • NAMESPACE:Iceberg 命名空間名稱。
  • TABLE_NAME:Iceberg 資料表名稱。

REST

如要使用 REST API 將變更提交至 Iceberg 資料表,請向 UpdateIcebergTable (CommitTable) 端點發出 POST 要求:

POST /iceberg/v1/restcatalog/v1/projects/PROJECT_ID/catalogs/CATALOG_ID/namespaces/NAMESPACE_NAME/tables/TABLE_NAME

要求主體必須包含有效的 Iceberg CommitTableRequest JSON 酬載,定義基本需求和要套用的中繼資料更新清單。

更改下列內容:

  • PROJECT_ID:您的 Google Cloud 專案 ID。
  • CATALOG_ID:目錄 ID。
  • NAMESPACE_NAME:目錄命名空間的名稱。
  • TABLE_NAME:Iceberg 資料表名稱。

後續步驟