重要
Unity Catalog Apache Iceberg REST 目录 API 在 Databricks Runtime 16.4 LTS 及更高版本中处于公共预览阶段。
Unity Catalog 具有 Iceberg REST 目录 API 的只读实现,该 API 已普遍可用。 建议使用此端点读取已启用 Iceberg 读取功能的 Delta 表。 有关详细信息,请参阅 从 Apache Iceberg 客户端(旧版)读取 Databricks 表 。
Apache Iceberg REST 目录允许支持的客户端(如 Apache Spark、Apache Flink 和 Trino)在 Azure Databricks 上读取和写入 Unity 目录注册的 Iceberg 表。 Snowflake 仅支持读取访问。
有关受支持的集成的完整列表,请参阅 Unity 目录集成。
使用 Unity 目录 Iceberg 目录终结点
Unity 目录提供 Iceberg REST 目录 API 规范的实现。
使用终结点 /api/2.1/unity-catalog/iceberg-rest
配置访问权限。 有关使用此 REST API 的详细信息,请参阅 Iceberg REST API 规范 。
注意
Azure Databricks 为一些 Iceberg 读取器客户端引入了凭证售卖。 Databricks 建议使用凭证售卖来控制对受支持系统的云存储位置的访问。 请参阅用于外部系统访问的 Unity Catalog 凭证售卖。
如果客户端不支持凭证售卖,则必须配置客户端对包含 Delta 或 Iceberg 表的文件和元数据的存储位置的访问。 有关配置详细信息,请参阅 Iceberg 客户端的文档。
要求
Azure Databricks 支持通过 Iceberg REST 目录访问 Unity Catalog 中的表。 必须在工作区启用 Unity Catalog 才能使用这些接口。 下表类型可通过 Iceberg REST 目录访问:
主题 | 读取 | 写入 |
---|---|---|
托管 Iceberg | 是的 | 是的 |
外部 Iceberg | 是的 | 否 |
托管 Delta(已启用 Iceberg 读取) | 是的 | 否 |
外部 Delta(已启用 Iceberg 读取) | 是的 | 否 |
通过 Iceberg REST 目录 API 读取时,外部 Iceberg 表不会自动刷新。 若要刷新,必须运行 REFRESH FOREIGN TABLE
才能读取最新的快照。 不支持对外部 Iceberg 表进行凭证售卖。
注意
必须配置 Delta 表才能通过 Iceberg REST 目录 API 进行访问。 请参阅 使用 Iceberg 客户端读取 Delta 表。
必须完成以下配置步骤,才能使用 Iceberg REST 目录配置从 Iceberg 客户端读取或写入 Azure Databricks 表的访问权限:
- 为元存储启用 外部数据访问 。 请参阅 在元存储上启用外部数据访问。
- 向配置集成的主体授予对包含表的架构的
EXTERNAL USE SCHEMA
权限。 请参阅 授予主体 Unity 目录特权。 - 使用 Azure Databricks 个人访问令牌或 OAuth 进行身份验证。 请参阅 授权访问 Azure Databricks 资源。
将 Iceberg 表与 Apache Spark 配合使用
以下示例演示如何使用 OAuth 身份验证将 Apache Spark 配置为通过 Iceberg REST 目录 API 访问 Azure Databricks 表:
"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
# Configuration for accessing Uniform tables in Unity Catalog
"spark.sql.catalog.<spark-catalog-name>": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.<spark-catalog-name>.type": "rest",
"spark.sql.catalog.<spark-catalog-name>.rest.auth.type": "oauth2",
"spark.sql.catalog.<spark-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog/iceberg-rest",
"spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri": "<workspace-url>/oidc/v1/token",
"spark.sql.catalog.<spark-catalog-name>.credential":"<oauth_client_id>:<oauth_client_secret>",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<uc-catalog-name>"
"spark.sql.catalog.<spark-catalog-name>.scope":"all-apis"
替换以下变量:
-
<uc-catalog-name>
:Unity Catalog 中包含表的目录的名称。 -
<spark-catalog-name>
:希望在 Spark 会话中分配目录的名称。 -
<workspace-url>
:Azure Databricks 工作区的 URL。 -
<oauth_client_id>
:身份验证主体的 OAuth 客户端 ID。 -
<oauth_client_secret>
:身份验证主体的 OAuth 客户端密码。
使用这些配置,可以使用 Apache Spark 查询 Unity 目录中的表。 为了访问多个目录中的表,必须单独配置每个目录。
使用 Spark 配置查询 Unity Catalog 中的表时,请记住以下几点:
只有在运行
"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"
时,才需要用到。Azure Databricks 会对所有表使用云对象存储。 必须将 iceberg-spark-runtime JAR 添加为 Spark 包:
- AWS:
org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
- 天蓝色:
org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
- GCP:
org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>
有关详细信息,请参阅 适用于 Spark 的 Iceberg AWS 集成的文档。
注意
从 Azure Databricks 访问 Iceberg 表时,不需要这些配置。 不支持将外部 Iceberg JAR 加载到 Azure Databricks 群集。
- AWS:
使用 Snowflake 读取 Azure Databricks 表
下面是建议的配置设置示例,通过连接到 Unity 目录中的 Iceberg REST 目录,允许 Snowflake 读取 Azure Databricks 表:
CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
CATALOG_SOURCE = ICEBERG_REST
TABLE_FORMAT = ICEBERG
CATALOG_NAMESPACE = '<uc-schema-name>'
REST_CONFIG = (
CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest',
WAREHOUSE = '<uc-catalog-name>'
ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
)
REST_AUTHENTICATION = (
TYPE = BEARER
BEARER_TOKEN = '<token>'
)
ENABLED = TRUE;
替换以下变量:
-
<catalog-integration-name>
: 要为注册到 Snowflake 的目录分配的名称。 -
<uc-schema-name>
:需要访问的 Unity Catalog 中架构的名称。 -
<uc-catalog-name>
:需要访问的 Unity Catalog 中目录的名称。 -
<workspace-url>
:Azure Databricks 工作区的 URL。 -
<token>
: 配置集成的主体的 PAT 令牌。
将 Azure Databricks 表与 PyIceberg 配合使用
下面是一个配置设置示例,通过连接到 Unity 目录中的 Iceberg REST 目录,允许 PyIceberg 访问 Azure Databricks 表:
catalog:
unity_catalog:
uri: https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest
warehouse: <uc-catalog-name>
token: <token>
替换以下变量:
-
<workspace-url>
:Azure Databricks 工作区的 URL。 -
<uc-catalog-name>
:需要访问的 Unity Catalog 中目录的名称。 -
<token>
: 配置集成的主体的 PAT 令牌。
REST API curl 示例
还可以使用此 curl
示例中的 REST API 调用来加载表:
curl -X GET -H "Authorization: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg-rest/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>
然后你应该会收到类似于以下内容的响应:
{
"metadata-location": "abfss://my-container@my-storage-account.dfs.core.chinacloudapi.cn/path/to/iceberg/table/metadata/file",
"metadata": <iceberg-table-metadata-json>,
"config": {
"expires-at-ms": "<epoch-ts-in-millis>",
"adls.sas-token.<storage-account-name>.dfs.core.chinacloudapi.cn": "<temporary-sas-token>"
}
}
注意
响应中的 expires-at-ms
字段指示凭证的过期时间,默认的过期时间为 1 小时。 要获得更好的性能,请让客户端在过期时间到来前缓存凭证,然后再请求新凭证。