更改表

借助 Lakehouse 运行时目录,您可以更改 Apache Iceberg 表以演变架构(例如添加列),以及配置表属性。这些更新可帮助您存储自定义元数据或选择启用 BigQuery 管理的功能(预览版),包括 BigQuery 数据操纵语言 (DML) 和自动表维护。

您可以使用 Google Cloud 控制台、Apache Spark、Trino、BigQuery(预览版)或 REST API 更改表。如需通过命令行更新表属性,您还可以使用 Google Cloud CLI。

准备工作

  1. 验证是否已为您的 Google Cloud 项目启用结算功能。

  2. 启用 BigLake API(如果尚未启用)。

    启用 API 所需的角色

    如需启用 API,您需要拥有 serviceusage.services.enable 权限。如果您创建了项目,则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则,您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

    启用 API

  3. 使用 Apache Iceberg REST 目录端点设置 Lakehouse 运行时目录。

所需的角色

如需获得更改表所需的权限,请让管理员向您授予项目和存储桶的以下 IAM 角色:

  • 在凭据自动售卖模式下更改表:BigLake Editor (roles/biglake.editor) - 项目
  • 在非凭证自动售卖模式下修改表:
    • BigLake Editor (roles/biglake.editor) - 项目
    • Storage Object User (roles/storage.objectUser) - 针对 Cloud Storage 存储桶

如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

表格功能和支持

在 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

  2. 选择现有目录,如果没有,请创建一个。

  3. 选择现有命名空间,如果没有,请创建一个。

  4. 在命名空间详情页面的表标签页上,点击要更改的表的名称。系统会打开表详情页面。

  5. 如需向表架构添加列,请执行以下操作:

    1. 点击架构标签页。
    2. 点击修改架构。
    3. 在新字段部分中,点击添加字段。在字段名称中,输入列名称,然后在类型列表中选择数据类型。如需改为以文本形式输入字段,请将以文本形式修改切换开关切换到开启位置,然后输入 JSON 或以逗号分隔的 name:type 对。
    4. 点击保存。
  6. 如需更新表属性,请执行以下操作:

    1. 点击详情标签页。
    2. 点击修改详细信息。
    3. 在属性部分中,更新现有属性值。如需添加自定义属性,请点击添加属性,然后在键和值字段中输入属性键和值。

      例如,如需启用 BigQuery DML 或自动表维护,请在 gcp.biglake.bigquery-dml.enabled 或 gcp.biglake.table-management.enabled 的值字段中输入 true。如需了解详情,请参阅配置表选项。

    4. 点击更新。

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

如需在 BigQuery 中更新 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 表的名称。

后续步骤