使用 BigLake Metastore 管理开源元数据

BigLake Metastore 是 Google Cloud 上数据分析产品的统一物理元数据服务。BigLake Metastore 提供元数据的单一可靠来源，可让您管理和访问来自多个来源的数据。您可以从 BigQuery 和 Dataproc 上的各种开放数据处理引擎访问 BigLake Metastore，这使其成为数据分析师和工程师的实用工具。

如需管理业务元数据，请参阅 Dataplex。

BigLake Metastore 的工作原理

BigLake Metastore 是一项无服务器服务，您无需预配资源即可使用。您可以将其用作 Dataproc 集群中 Hive Metastore 的无服务器替代方案。通过使用与 Hive 兼容的 API，BigLake Metastore 以与 Hive Metastore 相同的方式运行，您可以立即查询 BigQuery 中的开放格式表，而无需额外执行任何步骤。BigLake Metastore 仅支持 Apache Iceberg 表。

BigLake Metastore 提供 API、客户端库和数据引擎集成（例如 Apache Spark），用于管理目录、数据库和表。

限制

BigLake Metastore 有以下限制：

  • BigLake Metastore 不支持 Apache Hive 表。
  • Identity and Access Management (IAM) 角色和权限只能授予项目。不支持向资源授予 IAM 权限。
  • 不支持 Cloud Monitoring。
  • BigLake Metastore 目录和数据库有以下命名限制：
    • 名称不得超过 1,024 个字符。
    • 名称只能包含 UTF-8 字母（大写、小写）、数字和下划线。
    • 每个项目和区域组合的名称不得重复。
  • BigLake Metastore 表遵循与 BigQuery 表相同的命名规则。如需了解详情，请参阅表命名。

须知事项

在使用 BigLake Metastore 之前，您需要启用结算功能和 BigLake API。

  1. 请让您的管理员向您授予项目的 Service Usage Admin (roles/serviceusage.serviceUsageAdmin) IAM 角色。如需详细了解如何授予角色，请参阅管理访问权限。
  2. 为 Google Cloud 项目启用结算功能。了解如何检查项目是否已启用结算功能。

  3. 启用 BigLake API。

    启用该 API

所需的角色

  • 如需完全控制 BigLake Metastore 资源，您需要拥有 BigLake Admin 角色 (roles/biglake.admin)。如果您使用 BigQuery Spark 连接器服务账号、Dataproc Serverless 服务账号或 Dataproc 虚拟机服务账号，请向该账号授予 BigLake Admin 角色。
  • 如需获得 BigLake Metastore 资源的只读权限，您需要 BigLake Viewer 角色 (roles/biglake.viewer)。例如，在 BigQuery 中查询 BigLake Metastore 表时，用户或 BigQuery 连接服务账号必须具有 BigLake Viewer 角色。
  • 如需创建具有连接的 BigQuery 表，您需要 BigQuery Connection User 角色 (roles/bigquery.connectionUser)。如需详细了解如何共享连接，请参阅与用户共享连接。

根据应用场景的不同，调用 BigLake Metastore 的身份可以是用户或服务账号：

  • 用户：直接调用 BigLake Rest API，或者不使用来自 BigQuery 的连接查询 BigQuery Iceberg 表时。在这种情况下，BigQuery 使用用户的凭据。
  • BigQuery Cloud 资源连接：使用来自 BigQuery 的连接查询 BigQuery Iceberg 表时。BigQuery 使用连接服务账号凭据访问 BigLake Metastore。
  • BigQuery Spark 连接器：在 BigQuery Spark 存储过程中使用 Spark 和 BigLake Metastore 时。Spark 使用 Spark 连接器的服务账号凭据来访问 BigLake Metastore 和创建 BigQuery 表。
  • Dataproc Serverless 服务账号：在 Dataproc Serverless 中使用 Spark 和 BigLake 时。Spark 使用服务账号凭据。
  • Dataproc 虚拟机服务账号：使用 Dataproc（而非 Dataproc Serverless）时。Apache Spark 使用虚拟机服务账号凭据。

根据您的权限，您可以自行授予这些角色给自己，或者让管理员授予给您。如需详细了解如何授予角色，请参阅查看可针对资源授予的角色。

如需查看访问 BigLake Metastore 资源所需的确切权限，请展开所需权限部分：

所需权限

  • 项目级层的 biglake.tables.get，用于所有只读访问。查询 BigQuery Iceberg 表为只读操作。
  • 项目级层的 biglake.{catalogs|databases|tables}.*，用于所有读取和写入权限。通常，Apache Spark 需要能够读取和写入数据，包括创建、管理和查看目录、数据库和表的权限。
  • BigQuery Cloud 资源连接级层或更高级层的 bigquery.connections.delegate，用于使用连接创建 BigQuery Iceberg 表。

连接到 BigLake Metastore

以下部分介绍如何连接到 BigLake Metastore。这些部分将安装并使用 BigLake Apache Iceberg 目录插件，由以下方法中的 JAR 文件指示。目录插件从 Apache Spark 等开源引擎连接到 BigLake Metastore。

使用 Dataproc 虚拟机连接

如需使用 Dataproc 虚拟机连接到 BigLake Metastore，请执行以下操作：

  1. 使用 SSH 连接到 Dataproc。

  2. 在 Spark SQL CLI 中，使用以下语句安装和配置 Apache Iceberg 自定义目录以使用 BigLake Metastore：

    spark-sql \
  --packages ICEBERG_SPARK_PACKAGE \
  --jars BIGLAKE_ICEBERG_CATALOG_JAR \
  --conf spark.sql.catalog.SPARK_CATALOG=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.SPARK_CATALOG.catalog-impl=org.apache.iceberg.gcp.biglake.BigLakeCatalog \
  --conf spark.sql.catalog.SPARK_CATALOG.gcp_project=PROJECT_ID \
  --conf spark.sql.catalog.SPARK_CATALOG.gcp_location=LOCATION \
  --conf spark.sql.catalog.SPARK_CATALOG.blms_catalog=BLMS_CATALOG \
  --conf spark.sql.catalog.SPARK_CATALOG.warehouse=GCS_DATA_WAREHOUSE_FOLDER \
  --conf spark.sql.catalog.SPARK_HMS_CATALOG=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.SPARK_HMS_CATALOG.type=hive \
  --conf spark.sql.catalog.SPARK_HMS_CATALOG.uri=thrift://HMS_URI:9083

请替换以下内容：

  • ICEBERG_SPARK_PACKAGE：要使用的 Apache Iceberg with Spark 版本。我们建议您使用与 Dataproc 或 Dataproc Serverless 实例中的 Spark 版本匹配的 Spark 版本。如需查看可用的 Apache Iceberg 版本的列表，请参阅 Apache Iceberg 下载。例如，Apache Spark 3.3 的标志为：
    --packages org.apache.iceberg:iceberg-spark-runtime-3.3_2.13-1.2.1
  • BIGLAKE_ICEBERG_CATALOG_JAR：要安装的 Iceberg 自定义目录插件的 Cloud Storage URI。根据您的环境，选择以下选项之一：
    • Iceberg 1.2.0：gs://spark-lib/biglake/biglake-catalog-iceberg1.2.0-0.1.1-with-dependencies.jar
    • Iceberg 0.14.0：gs://spark-lib/biglake/biglake-catalog-iceberg0.14.0-0.1.1-with-dependencies.jar
  • SPARK_CATALOG：Spark 的目录标识符。它关联到 BigLake Metastore 目录。
  • PROJECT_ID：Spark 目录关联的 BigLake Metastore 目录的 Google Cloud 项目 ID。
  • LOCATION：Spark 目录关联的 BigLake Metastore 目录的 Google Cloud 位置。
  • BLMS_CATALOG：Spark 目录关联的 BigLake Metastore 目录 ID。该目录不需要已经存在，可以在 Spark 中创建。
  • GCS_DATA_WAREHOUSE_FOLDER：Cloud Storage 文件夹，Spark 在其中创建所有文件。它以 gs:// 开头。
  • HMS_DB：（可选）包含要复制的表的 HMS 数据库。
  • HMS_TABLE：（可选）要复制的 HMS 表。
  • HMS_URI：（可选）HMS Thrift 端点。

使用 Dataproc 集群连接

或者，您可以将 Dataproc 作业提交到集群。以下示例安装相应的 Iceberg 自定义目录。

如需使用 Dataproc 集群连接，请使用以下规范提交作业：

CONFS="spark.sql.catalog.SPARK_CATALOG=org.apache.iceberg.spark.SparkCatalog,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.catalog-impl=org.apache.iceberg.gcp.biglake.BigLakeCatalog,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.gcp_project=PROJECT_ID,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.gcp_location=LOCATION,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.blms_catalog=BLMS_CATALOG,"
CONFS+="spark.sql.catalog.SPARK_CATALOG.warehouse=GCS_DATA_WAREHOUSE_FOLDER,"
CONFS+="spark.jars.packages=ICEBERG_SPARK_PACKAGE"

gcloud dataproc jobs submit spark-sql --cluster=DATAPROC_CLUSTER \
  --project=DATAPROC_PROJECT_ID \
  --region=DATAPROC_LOCATION \
  --jars=BIGLAKE_ICEBERG_CATALOG_JAR \
  --properties="${CONFS}" \
  --file=QUERY_FILE_PATH

请替换以下内容：

  • DATAPROC_CLUSTER：要将作业提交到的 Dataproc 集群。
  • DATAPROC_PROJECT_ID：Dataproc 集群的项目 ID。此 ID 可以不同于 PROJECT_ID。
  • DATAPROC_LOCATION：Dataproc 集群的位置。此位置可以不同于 LOCATION。
  • QUERY_FILE_PATH：包含要运行的查询的文件的路径。

使用 Dataproc Serverless 连接

同样，您可以将批处理工作负载提交到 Dataproc Serverless。为此，请按照批处理工作负载说明操作，并使用以下额外标志：

  • --properties="${CONFS}"
  • --jars=BIGLAKE_ICEBERG_CATALOG_JAR

使用 BigQuery 存储过程连接

您可以使用 BigQuery 存储过程来运行 Dataproc Serverless 作业。该过程类似于直接在 Dataproc 中运行 Dataproc Serverless 作业。

创建 Metastore 资源

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

创建目录

目录名称有限制条件，如需了解详情，请参阅限制。如需创建目录，请选择以下选项之一：

API

使用 projects.locations.catalogs.create 方法并指定目录名称。

Spark SQL

CREATE NAMESPACE SPARK_CATALOG;

Terraform

这会在“google_biglake_catalog.default.id”变量指定的目录中创建一个“HIVE”类型的名为“my_database”的 BigLake 数据库。如需了解详情，请参阅 Terraform BigLake 文档。

resource "google_biglake_catalog" "default" {
name     = "my_catalog"
location = "US"
}

创建数据库

数据库名称有限制条件，如需了解详情，请参阅限制。为确保数据库资源与数据引擎兼容，我们建议使用数据引擎创建数据库，而不是手动创建资源正文。如需创建数据库，请选择以下选项之一：

API

使用 projects.locations.catalogs.databases.create 方法并指定数据库名称。

Spark SQL

CREATE NAMESPACE BLMS_DB;

请替换以下内容：

  • BLMS_DB：要创建的 BigLake Metastore 数据库 ID

Terraform

这会在“google_biglake_catalog.default.id”变量指定的目录中创建一个“HIVE”类型的名为“my_database”的 BigLake 数据库。如需了解详情，请参阅 Terraform BigLake 文档。

resource "google_biglake_database" "default" {
name    = "my_database"
catalog = google_biglake_catalog.default.id
type    = "HIVE"
hive_options {
  location_uri = "gs://${google_storage_bucket.default.name}/${google_storage_bucket_object.metadata_directory.name}"
  parameters = {
    "owner" = "Alex"
  }
}
}

创建表

表名称有限制条件。如需了解详情，请参阅表命名。如需创建表，请选择以下选项之一：

API

使用 projects.locations.catalogs.databases.tables.create 方法并指定表名称。

Spark SQL

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

请替换以下内容：

  • BLMS_TABLE：要创建的 BigLake Metastore 表 ID

Terraform

这会在“google_biglake_database.default.id”变量指定的数据库中创建一个“HIVE”类型的名为“my_table”的 BigLake Metastore 表。如需了解详情，请参阅 Terraform 提供程序文档：BigLake 表。

resource "google_biglake_table" "default" {
name     = "my-table"
database = google_biglake_database.default.id
type     = "HIVE"
hive_options {
  table_type = "MANAGED_TABLE"
  storage_descriptor {
    location_uri  = "gs://${google_storage_bucket.default.name}/${google_storage_bucket_object.data_directory.name}"
    input_format  = "org.apache.hadoop.mapred.SequenceFileInputFormat"
    output_format = "org.apache.hadoop.hive.ql.io.HiveSequenceFileOutputFormat"
  }
  parameters = {
    "spark.sql.create.version"          = "3.1.3"
    "spark.sql.sources.schema.numParts" = "1"
    "transient_lastDdlTime"             = "1680894197"
    "spark.sql.partitionProvider"       = "catalog"
    "owner"                             = "Alex"
    "spark.sql.sources.schema.part.0" = jsonencode({
      "type" : "struct",
      "fields" : [
        { "name" : "id", "type" : "integer",
          "nullable" : true,
          "metadata" : {}
        },
        {
          "name" : "name",
          "type" : "string",
          "nullable" : true,
          "metadata" : {}
        },
        {
          "name" : "age",
          "type" : "integer",
          "nullable" : true,
          "metadata" : {}
        }
      ]
    })
    "spark.sql.sources.provider" = "iceberg"
    "provider"                   = "iceberg"
  }
}
}

E2E Terraform 示例

此 GitHub 示例提供了一个可运行的 E2E 示例，该示例创建了一个“BigLake”Metastore 目录、数据库和表。如需详细了解如何使用此示例，请参阅基本 Terraform 命令。

将 Iceberg 表从 Hive Metastore 复制到 BigLake Metastore

如需创建 Iceberg 表并将 Hive Metastore 表复制到 BigLake Metastore，请使用以下 Spark SQL 语句：

CREATE TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE
  (id bigint, data string) USING iceberg
  TBLPROPERTIES(hms_table='HMS_DB.HMS_TABLE');

查询 BigLake Iceberg 表时推荐使用 BigLake Metastore。在 Spark 中创建 Iceberg 表时，您可以选择同时创建关联的 BigLake Iceberg 表。

如需在 Spark 中创建 Iceberg 表并同时自动创建 BigLake Iceberg 表，请使用以下 Spark SQL 语句：

  CREATE TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE
    (id bigint, data string) USING iceberg
    TBLPROPERTIES(bq_table='BQ_TABLE_PATH',
    bq_connection='BQ_RESOURCE_CONNECTION');

请替换以下内容：

  • BQ_TABLE_PATH：要创建的 BigLake Iceberg 表的路径。请遵循 BigQuery 表路径语法。如果未指定项目，它会使用与 BigLake Metastore 目录相同的项目。

  • BQ_RESOURCE_CONNECTION（可选）：格式为 project.location.connection-id。如果指定，BigQuery 查询会使用 Cloud 资源连接凭据来访问 BigLake Metastore。如果未指定，BigQuery 会创建一个常规外部表，而不是 BigLake 表。

如需手动创建具有指定 BigLake Metastore 表 URI (blms://…) 的 BigLake Iceberg 表链接，请使用以下 BigQuery SQL 语句：

CREATE EXTERNAL TABLE 'BQ_TABLE_PATH'
  WITH CONNECTION `BQ_RESOURCE_CONNECTION`
  OPTIONS (
          format = 'ICEBERG',
          uris = ['blms://projects/PROJECT_ID/locations/LOCATION/catalogs/BLMS_CATALOG/databases/BLMS_DB/tables/BLMS_TABLE']
          )

查看 Metastore 资源

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

查看目录

如需查看目录中的所有数据库，请使用 projects.locations.catalogs.list 方法并指定目录名称。

如需查看目录的相关信息，请使用 projects.locations.catalogs.get 方法并指定目录名称。

查看数据库

如需查看数据库，请执行以下操作：

API

如需查看数据库中的所有表，请使用 projects.locations.catalogs.databases.list 方法并指定数据库名称。

如需查看数据库的相关信息，请使用 projects.locations.catalogs.databases.get 方法并指定数据库名称。

Spark SQL

如需查看目录中的所有数据库，请使用以下语句：

SHOW { DATABASES | NAMESPACES } IN SPARK_CATALOG;

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

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

查看表

如需查看数据库中的所有表或查看指定的表，请执行以下操作：

API

如需查看数据库中的所有表，请使用 projects.locations.catalogs.databases.tables.list 方法并指定数据库名称。

如需查看表的相关信息，请使用 projects.locations.catalogs.databases.tables.get 方法并指定表名称。

Spark SQL

如需查看数据库中的所有表，请使用以下语句：

SHOW TABLES IN SPARK_CATALOG.BLMS_DB;

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

DESCRIBE TABLE [EXTENDED] SPARK_CATALOG.BLMS_DB.BLMS_TABLE;

修改 Metastore 资源

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

更新表

为避免多个作业尝试同时更新同一个表时发生冲突，BigLake Metastore 使用乐观锁定。如需使用乐观锁定，您首先需要使用 GetTable 方法获取表的当前版本（称为 etag）。然后，您可以对表进行更改并使用 UpdateTable 方法，并传入先前获取的 etag。如果在您获取 etag 后另一个作业更新该表，则 UpdateTable 方法会失败。此措施可确保一次只有一个作业可以更新表，从而防止发生冲突。

如需更新表，请选择以下选项之一：

API

使用 projects.locations.catalogs.databases.tables.patch 方法并指定表名称。

Spark SQL

如需了解 SQL 中的表更新选项，请参阅 ALTER TABLE。

重命名表

如需重命名表，请选择以下选项之一：

API

使用 projects.locations.catalogs.databases.tables.rename 方法并指定表名称和 newName 值。

Spark SQL

ALTER TABLE BLMS_TABLE RENAME TO NEW_BLMS_TABLE;

请替换以下内容：

  • NEW_BLMS_TABLE：BLMS_TABLE 的新名称。必须与 BLMS_TABLE 位于同一数据集中。

删除 Metastore 资源

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

删除目录

如需删除目录，请选择以下选项之一：

API

使用 projects.locations.catalogs.delete 方法并指定目录名称。此方法不会删除 Google Cloud 上的关联文件。

Spark SQL

DROP NAMESPACE SPARK_CATALOG;

删除数据库

如需删除数据库，请选择以下选项之一：

API

使用 projects.locations.catalogs.databases.delete 方法并指定数据库名称。此方法不会删除 Google Cloud 上的关联文件。

Spark SQL

DROP NAMESPACE SPARK_CATALOG.BLMS_DB;

删除表

如需删除表，请选择以下选项之一：

API

使用 projects.locations.catalogs.databases.tables.delete 方法并指定表名称。此方法不会删除 Google Cloud 上的关联文件。

Spark SQL

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

DROP TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE;

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

DROP TABLE SPARK_CATALOG.BLMS_DB.BLMS_TABLE PURGE;