在 BigLake metastore 中管理 Iceberg 资源

BigLake metastore 是一种单一的共享 metastore，可实现数据处理引擎之间的数据共享，从而无需为开源工作负载维护单独的 metastore。

本文档介绍了如何在 BigLake metastore 中创建、查看、修改和删除 Iceberg 资源。

准备工作

  1. Make sure that billing is enabled for your Google Cloud project.

    了解如何检查项目是否已启用结算功能。

  2. Enable the BigQuery, BigQuery Storage, and Dataproc APIs.

    Enable the APIs

  3. 可选：了解 BigQuery metastore 的工作原理以及为什么您应该使用它。

所需的角色

如需获得在 BigLake 元存储区中管理 Iceberg 资源所需的权限，请让管理员向您授予项目的以下 IAM 角色：

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

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

创建 metastore 资源

以下部分介绍如何在 BigLake metastore 中创建资源。

创建命名空间

从下列选项中选择一项：

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 位置

Spark SQL 

CREATE NAMESPACE SPARK_CATALOG.NAMESPACE;

替换以下内容：

  • SPARK_CATALOG：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

创建 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：最新 Iceberg 元数据文件的 Cloud Storage URI。例如 gs://mybucket/mytable/metadata/1234.metadata.json。
  • CONNECTION_ID：您与 Cloud Storage 的连接的 ID。

Spark SQL 

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

替换以下内容：

  • SPARK_CATALOG：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：最新 Iceberg 元数据文件的 Cloud Storage URI。例如 gs://mybucket/mytable/metadata/1234.metadata.json。

查看 metastore 资源

以下部分介绍如何查看 BigLake metastore 中的资源。

查看命名空间

从下列选项中选择一项：

API

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

Spark SQL

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

SHOW { DATABASES | NAMESPACES } IN SPARK_CATALOG;

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

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

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

替换以下内容：

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

查看表

从下列选项中选择一项：

API

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

Spark SQL

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

SHOW TABLES IN SPARK_CATALOG.NAMESPACE;

替换以下内容：

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

如需查看指定表的相关信息，请使用以下语句：

DESCRIBE TABLE [EXTENDED]
SPARK_CATALOG.NAMESPACE.TABLE;

替换以下内容：

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

修改 metastore 资源

以下部分介绍如何修改 BigLake metastore 中的资源。

更新命名空间

从下列选项中选择一项：

API

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

Spark SQL

使用 ALTER DATABASE 语句。

更新 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

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

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

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

Spark SQL

使用 ALTER TABLE 语句。

删除 metastore 资源

以下部分介绍如何删除 BigLake metastore 中的资源。

删除命名空间

从下列选项中选择一项：

API

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

Spark SQL 

DROP NAMESPACE SPARK_CATALOG.NAMESPACE;

替换以下内容：

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

删除表

从下列选项中选择一项：

API

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

Spark SQL

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

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE;

替换以下内容：

  • SPARK_CATALOG：Spark 目录的名称
  • NAMESPACE：您的命名空间名称
  • TABLE：要丢弃的表的名称

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

DROP TABLE SPARK_CATALOG.NAMESPACE.TABLE PURGE;

替换以下内容：

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

后续步骤