在 Lakehouse 运行时目录中创建和管理资源

Lakehouse for Apache Iceberg 支持通过 Lakehouse 运行时目录进行资源管理。

借助此共享目录，您无需为不同数据处理引擎中的开源工作负载维护多个目录。支持的操作包括创建、查看、修改和删除命名空间和表等资源。

准备工作

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

  2. 启用 BigQuery、BigQuery Storage 和 Managed Service for Apache Spark API。

    启用 API 所需的角色

    如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予 角色。

    启用 API

所需的角色

如需获得在 Lakehouse 运行时目录中管理 Apache Iceberg 资源所需的权限，请让管理员未您授予项目的以下 IAM 角色：

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

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

创建目录资源

以下部分介绍如何在 Lakehouse 运行时目录中创建资源。

创建命名空间

从下列选项中选择一项：

API

使用 datasets.insert 方法，并在传入的 数据集资源中指定 ExternalCatalogDatasetOptions 字段。

{
  "datasetReference": {
    "projectId": "PROJECT_ID",
    "datasetId": "DATASET_ID"
  },
  "externalCatalogDatasetOptions": {
    "defaultStorageLocationUri": "URI",
    "parameters": {
      ...
    }
  },
  "location": "LOCATION"
}

替换以下内容：

  • PROJECT_ID：包含目标数据集的项目的 ID。
  • DATASET_ID：目标数据集的 ID。
  • URI：数据集中所有表的 Cloud Storage URI。
  • LOCATION：要在其中创建数据集的 BigQuery 位置。

Apache Spark SQL 

CREATE NAMESPACE SPARK_CATALOG.NAMESPACE;

替换以下内容：

  • SPARK_CATALOG：Apache Spark 目录的名称。
  • NAMESPACE：新命名空间的名称。

Terraform 

provider "google" {
  project = "PROJECT_ID"
}

resource "google_bigquery_dataset" "default" {
  dataset_id = "DATASET_ID"
  location   = "LOCATION"

  external_catalog_dataset_options {
    default_storage_location_uri = "URI"
    parameters = {
      ...
    }
  }
}

替换以下内容：

  • PROJECT_ID：包含目标数据集的项目的 ID。
  • DATASET_ID：目标数据集的 ID。
  • LOCATION：要在其中创建数据集的 BigQuery 位置。
  • URI：数据集中所有表的 Cloud Storage URI。

创建 Apache Iceberg 表

从下列选项中选择一项：

API

使用 tables.insert 方法，并在传入的表资源中指定 ExternalCatalogTableOptions 字段。

{
  "tableReference": {
    "projectId": "PROJECT_ID",
    "datasetId": "DATASET_ID",
    "tableId": "TABLE_ID"
  },
  "externalCatalogTableOptions": {
    "parameters": {
      "table_type": "iceberg",
      "metadata_location": "METADATA_URI"
    },
    "connection_id": "CONNECTION_ID"
  }
}

替换以下内容：

  • PROJECT_ID：包含目标表的项目的 ID。
  • DATASET_ID：包含目标表的数据集的 ID。
  • TABLE_ID：目标表的 ID。
  • METADATA_URI：最新 Apache Iceberg 元数据文件的 Cloud Storage URI。例如，gs://mybucket/mytable/metadata/1234.metadata.json。
  • CONNECTION_ID：与 Cloud Storage 的连接的 ID。

Apache Spark SQL 

CREATE TABLE SPARK_CATALOG.NAMESPACE.TABLE
  (id bigint, data string) USING iceberg;

替换以下内容：

  • SPARK_CATALOG：Apache Spark 目录的名称。
  • NAMESPACE：命名空间的名称。
  • TABLE：新表的名称。

Terraform 

resource "google_bigquery_table" "default" {
  deletion_protection = false
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "TABLE"

  external_catalog_table_options {
    storage_descriptor {
      location_uri  = "STORAGE_URI"
      input_format  = "org.apache.hadoop.mapred.FileInputFormat"
      output_format = "org.apache.hadoop.mapred.FileOutputFormat"
    }
    parameters = {
      "table_type"        = "iceberg"
      "metadata_location" = "METADATA_URI"
      "write.parquet.compression-codec" : "zstd"
      "EXTERNAL" : "TRUE"
    }
  }
}

替换以下内容：

  • TABLE：目标表的名称。
  • STORAGE_URI：用于存储表数据的 Cloud Storage URI，以 gs:// 开头。
  • METADATA_URI：最新 Apache Iceberg 元数据文件的 Cloud Storage URI。例如，gs://mybucket/mytable/metadata/1234.metadata.json。

查看目录资源

以下部分介绍如何在 Lakehouse 运行时目录中查看资源。

查看命名空间

从下列选项中选择一项：

API

使用 datasets.list 方法 可查看所有命名空间，使用 datasets.get 方法 可查看有关已定义命名空间的信息。

Apache Spark SQL

如需查看目录中的所有命名空间，请使用以下语句：

SHOW { DATABASES | NAMESPACES } IN SPARK_CATALOG;

将 SPARK_CATALOG 替换为 Apache Spark 目录的名称。

如需查看有关已定义命名空间的信息，请使用以下语句：

DESCRIBE { DATABASE | NAMESPACE } [EXTENDED]
SPARK_CATALOG.NAMESPACE;

替换以下内容：

  • SPARK_CATALOG：Apache Spark 目录的名称。
  • NAMESPACE：命名空间的名称。

查看表

从下列选项中选择一项：

API

使用 tables.list方法 可查看命名空间中的所有表，使用 tables.get方法 可查看有关已定义表的信息。

Apache Spark SQL

如需查看命名空间中的所有表，请使用以下语句：

SHOW TABLES IN SPARK_CATALOG.NAMESPACE;

替换以下内容：

  • SPARK_CATALOG：Apache Spark 目录的名称。
  • NAMESPACE：命名空间的名称。

如需查看有关已定义表的信息，请使用以下语句：

DESCRIBE TABLE [EXTENDED]
SPARK_CATALOG.NAMESPACE.TABLE;

替换以下内容：

  • SPARK_CATALOG：Apache Spark 目录的名称。
  • NAMESPACE：命名空间的名称。
  • TABLE：表的名称。

修改目录资源

以下部分介绍如何在 Lakehouse 运行时目录中修改资源。

更新命名空间

从下列选项中选择一项：

API

使用 datasets.patch 方法，并更新数据集资源中的 ExternalCatalogDatasetOptions 字段。不建议使用 datasets.update 方法，因为它会替换整个数据集资源。

Apache Spark SQL

使用 ALTER DATABASE 语句。

更新 Apache Iceberg 表

从下列选项中选择一项：

API

使用 tables.patch 方法，并更新表资源中的 ExternalCatalogTableOptions 字段。不建议使用 tables.update 方法，因为它会替换整个表资源。

如需更新架构或元数据文件，请使用 tables.patch 方法并将 autodetect_schema 属性设置为 true：

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID?autodetect_schema=true

替换以下内容：

  • PROJECT_ID：包含要更新的表的项目的 ID。
  • DATASET_ID：包含要更新的表的数据集的 ID。
  • TABLE_ID：要更新的表的 ID。

在请求正文中，为每个字段指定更新后的值。例如，如需更新 Apache Iceberg 表的元数据位置，请为 metadata_location 字段指定更新后的值：

{
  "externalCatalogTableOptions": {
    "parameters": {"metadata_location": "METADATA_URI"}
  },
  "schema": null
}'

将 METADATA_URI 替换为最新 Apache Iceberg 元数据文件的 Cloud Storage URI。例如，gs://mybucket/mytable/metadata/1234.metadata.json。

Apache Spark SQL

使用 ALTER TABLE 语句。

删除目录资源

以下部分介绍如何在 Lakehouse 运行时目录中删除资源。

删除命名空间

从下列选项中选择一项：

API

使用 datasets.delete 方法。 将 deleteContents 参数设置为 true 可删除命名空间中的表。

Apache Spark SQL 

DROP NAMESPACE SPARK_CATALOG.NAMESPACE;

替换以下内容：

  • SPARK_CATALOG：Apache Spark 目录的名称。
  • NAMESPACE：命名空间的名称。

删除表

从下列选项中选择一项：

API

使用 tables.delete 方法并指定表的名称。此方法不会删除 Cloud Storage 中的关联文件。

Apache Spark SQL

如需仅删除表，请使用以下语句：

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE;

替换以下内容：

  • SPARK_CATALOG：Apache Spark 目录的名称。
  • NAMESPACE：命名空间的名称。
  • TABLE：要删除的表的名称。

如需删除表并删除 Cloud Storage 中的关联文件，请使用以下语句：

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE PURGE;

替换以下内容：

  • SPARK_CATALOG：Apache Spark 目录的名称。
  • NAMESPACE：命名空间的名称。
  • TABLE：要删除的表的名称。

后续步骤