Apache Iceberg 视图概览

借助 Apache Iceberg 视图,您可以使用 SQL 定义开放的非物化逻辑表,并从兼容 Iceberg 的引擎(例如 Apache Spark、Trino、Apache Flink、PyIceberg 和 dbt)中使用这些表。您可以使用 Iceberg 视图构建模块化 SQL 流水线,并在 Iceberg 表上公开精选的零复制投影。Iceberg 视图由 Lakehouse 运行时目录通过 Apache Iceberg REST 目录端点进行管理,并遵循 Apache Iceberg 视图规范和 Iceberg REST OpenAPI 规范。

本文档将这些视图称为 Iceberg 视图。

与 BigQuery 授权视图不同,Iceberg 视图由计算引擎在客户端进行评估。Iceberg 视图是您通过开源引擎创建、管理和查询的目录对象。

功能

支持以下功能:

  • 完整的视图生命周期:通过与 Iceberg 兼容的开源引擎(例如 Apache Spark 和 Trino)创建、替换、更改属性、列出、检查和删除 Iceberg 视图。
  • 丰富的视图定义:使用列别名、列级和视图级注释、自定义属性、联接、聚合、通用表表达式 (CTE)、UNION ALL、子查询、嵌套视图和底层表上的时间旅行来定义视图。
  • 灵活的身份验证:将最终用户凭证或凭证发放与标准 Cloud Storage 存储桶和分层命名空间存储桶搭配使用。
  • 目录支持:在多存储桶目录和单存储桶目录中创建视图。

您只能通过连接到 Apache Iceberg REST 目录端点的 Iceberg 兼容开源引擎来创建、管理和查询 Iceberg 视图。如需了解详情,请参阅限制。

对于 Spark,请使用 Spark 3.5 或更高版本以及 Iceberg 运行时 1.6.0 或更高版本。使用 Iceberg 运行时 1.10.0 或更高版本,以便 Spark 通过目录的 GET /v1/config 响应发现支持的视图端点。设置 spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,以便 Spark 将视图 DDL 和解析委托给 Apache Iceberg REST 目录端点。

对于 Trino,请使用 Trino 482 或更高版本。如需了解详情,请参阅 Trino 支持。

Iceberg 视图的工作原理

Iceberg 视图将其 SQL 定义、架构和属性存储在 Cloud Storage 中 VIEW_LOCATION/metadata/ 下的版本化 metadata.json 文件中。Lakehouse 运行时目录会跟踪每个视图的当前元数据位置,并通过 Apache Iceberg REST 目录端点的视图端点公开视图。

您的 Compute Engine 会在客户端评估 Iceberg 视图。运行 SELECT * FROM my_view 时,引擎会从目录中加载视图定义,解析每个引用的表和嵌套视图,然后针对底层 Iceberg 表运行查询。目录不会代表您运行查询。

每次您将视图替换为 CREATE OR REPLACE VIEW 时,目录都会写入一个新的 metadata.json 文件,将新版本和架构附加到视图元数据,并保留视图的 view-uuid。version.history.num-entries 属性限制保留的版本数量。如需了解详情,请参阅查看属性。

表和视图在目录命名空间中共享相同的标识符命名空间。您无法创建与现有表同名的视图,也无法将表替换为视图。

所需的角色和权限

由于 Compute Engine 会在客户端评估视图,因此查询视图需要对该视图以及该视图引用的每个表和嵌套视图拥有权限。

如需获得创建、管理和查询 Iceberg 视图所需的权限,请让您的管理员为您授予项目和存储桶的以下 IAM 角色:

  • 创建、替换、更改和删除视图:BigLake Editor (roles/biglake.editor) - 您的项目
  • 列出并检查视图定义:BigLake Viewer (roles/biglake.viewer) - 您的项目
  • 在凭据自动售卖模式下查询视图:BigLake Viewer (roles/biglake.viewer) - 您的项目
  • 在最终用户凭证模式下查询视图:
    • BigLake Viewer (roles/biglake.viewer) - 您的项目
    • Storage Object Viewer (roles/storage.objectViewer) - Cloud Storage 存储桶
  • 在最终用户凭据模式下写入视图元数据文件:Storage Object User (roles/storage.objectUser) - 针对 Cloud Storage 存储桶

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

这些预定义角色包含创建、管理和查询 Iceberg 视图所需的权限。如需查看所需的确切权限,请展开所需权限部分:

所需权限

您需要具备以下权限才能创建、管理和查询 Iceberg 视图:

  • 创建视图:
    • biglake.views.create (在命名空间上)
    • 针对视图引用的每个 Iceberg 表的 biglake.tables.get 权限
  • 列表视图: biglake.views.list 在命名空间中
  • 获取视图详细信息:针对视图的 biglake.views.get 权限
  • 更改视图:
    • 针对视图的 biglake.views.update 权限
    • 针对新视图定义引用的每个 Iceberg 表的 biglake.tables.get 权限
  • 删除视图:针对视图的 biglake.views.delete 权限
  • 查询视图:
    • 针对视图和任何嵌套视图的 biglake.views.get 权限
    • 针对视图引用的每个 Iceberg 表的 biglake.tables.get 权限
  • 在凭据自动售卖模式下读取表数据:针对视图引用的每个 Iceberg 表的 biglake.tables.getData 角色
  • 在最终用户凭证模式下读取视图元数据和表数据:针对 Cloud Storage 存储桶的 storage.objects.get
  • 在最终用户凭据模式下写入视图元数据文件:针对 Cloud Storage 存储桶的 storage.objects.create

您也可以使用自定义角色或其他预定义角色来获取这些权限。

下表将每个查看权限映射到其授权的 Apache Iceberg REST 目录端点操作:

权限 资源 端点操作 包含在预定义角色中
biglake.views.create 命名空间 CreateIcebergView roles/biglake.admin,roles/biglake.editor
biglake.views.get 查看 GetIcebergView,CheckIcebergViewExists roles/biglake.admin、roles/biglake.editor、roles/biglake.viewer、roles/biglake.metadataViewer
biglake.views.update 查看 UpdateIcebergView roles/biglake.admin,roles/biglake.editor
biglake.views.delete 查看 DeleteIcebergView roles/biglake.admin,roles/biglake.editor
biglake.views.list 命名空间 ListIcebergViewIdentifiers roles/biglake.admin、roles/biglake.editor、roles/biglake.viewer、roles/biglake.metadataViewer

如需了解详情,请参阅 Lakehouse IAM 角色。

支持的视图端点

当引擎使用 GET /v1/config?warehouse=WAREHOUSE_URI 初始化目录会话时,Apache Iceberg REST 目录端点会在 endpoints 列表中通告以下视图端点。在下表中,{prefix} 为 projects/PROJECT_ID/catalogs/CATALOG_ID。

方法和路径 操作 说明 所需权限
GET /v1/{prefix}/namespaces/{namespace}/views ListIcebergViewIdentifiers 列出命名空间中的视图标识符。支持 pageToken 和 pageSize。不包含表格。 命名空间上的 biglake.views.list
POST /v1/{prefix}/namespaces/{namespace}/views CreateIcebergView 创建视图,将初始 00000-UUID.metadata.json 文件写入 Cloud Storage,并注册视图。 命名空间上的 biglake.views.create
GET /v1/{prefix}/namespaces/{namespace}/views/{view} GetIcebergView 加载当前视图元数据和元数据位置。 针对视图的 biglake.views.get 权限
POST /v1/{prefix}/namespaces/{namespace}/views/{view} UpdateIcebergView 验证乐观并发要求,并将更新提交到新的 metadata.json 文件。 针对视图的 biglake.views.update 权限
DELETE /v1/{prefix}/namespaces/{namespace}/views/{view} DeleteIcebergView 从目录中移除视图,并清除其视图级 Identity and Access Management (IAM) 政策。 针对视图的 biglake.views.delete 权限
HEAD /v1/{prefix}/namespaces/{namespace}/views/{view} CheckIcebergViewExists 检查视图是否存在。 针对视图的 biglake.views.get 权限

管理操作

您可以对 Iceberg 视图执行以下管理操作:

  • 创建视图:使用 Spark 或 Apache Iceberg REST 目录端点 (CreateIcebergView) 在一个或多个 Iceberg 表上定义视图。
  • 列表视图:使用 Spark 或 Apache Iceberg REST Catalog 端点 (ListIcebergViewIdentifiers) 列出命名空间中的视图标识符。
  • 获取视图详情:使用 Spark 或 Apache Iceberg REST 目录端点 (GetIcebergView) 检查视图的架构、SQL 定义和属性。
  • 查询视图:从与 Iceberg 兼容的开源引擎(例如 Spark)对视图运行查询。
  • 更改视图:使用 Spark 或 Apache Iceberg REST 目录端点 (UpdateIcebergView) 替换视图定义或更新视图属性。
  • 删除视图:使用 Spark 或 Apache Iceberg REST 目录端点 (DeleteIcebergView) 从目录中删除视图。

限制

Iceberg 视图存在以下限制:

  • 仅限开源引擎。您只能通过 Apache Iceberg REST 目录端点,从与 Iceberg 兼容的开源引擎创建、管理和查询 Iceberg 视图。BigQuery SQL、bq 命令行工具、 Google Cloud 控制台、gcloud CLI 和 Terraform 不支持 Iceberg 视图。
  • 支持的目录类型。Iceberg 视图仅在多存储桶目录和单存储桶目录中受支持。目录会拒绝针对 BigQuery 目录和联合目录的视图操作,并返回 400 Bad Request (FAILED_PRECONDITION) 错误。
  • 不支持的 REST 视图操作。
    • 不支持重命名视图(POST /v1/{prefix}/views/rename 或 ALTER VIEW ... RENAME TO)。如需重命名视图,请创建一个具有新名称的视图,然后删除原始视图。
    • 不支持注册现有视图 metadata.json 文件 (registerView)。
    • 不支持物化视图。仅支持逻辑 Iceberg 视图。
  • 对视图进行时间旅行。您无法将 TIMESTAMP AS OF 或 VERSION AS OF 应用于视图标识符。视图定义可以对它查询的底层表应用时间旅行。如需了解详情,请参阅在底层表上创建具有时间旅行功能的视图。
  • 查看存储位置。
    • 在单存储桶目录中,不支持自定义视图位置。视图位置必须与默认路径 NAMESPACE_LOCATION/VIEW_NAME 匹配。
    • 在多存储桶目录中,自定义视图位置必须位于命名空间的存储空间 URI 前缀和目录的允许存储位置内。
    • 创建视图后,其存储位置不可变。尝试设置其他位置会失败,并显示 400 Bad Request 错误。

查看属性

Iceberg 视图支持 Apache Iceberg 定义的视图属性。下表介绍了目录如何处理这些属性:

属性 默认值 行为
write.metadata.compression-codec gzip 默认情况下,目录会写入经过 gzip 压缩的 .gz.metadata.json 文件。设置为 none 可写入未压缩的 .metadata.json 文件。该值区分大小写。您可以在创建时或使用 ALTER VIEW ... SET TBLPROPERTIES 设置此属性。
write.metadata.path VIEW_LOCATION/metadata 对于视图,系统会忽略该字段。目录始终在 VIEW_LOCATION/metadata/VERSION-UUID.metadata.json 下写入视图元数据文件。
version.history.num-entries 10 必须是正整数。限制目录在视图的 versions 列表和 version-log 中保留的条目数。当提交内容超出此限制时,目录会移除最早的条目,并始终保留当前版本和提交内容添加的版本。版本日志旨在用于审核和管理回滚;Compute Engine 不支持使用 SQL 查询历史视图版本。

后续步骤