启用对流式表和物化视图的外部数据访问

Important

此功能目前以公共预览版提供。

如果已启用对 Unity 目录的外部数据访问，则还可以向管道数据集添加外部数据访问权限。这使外部 Delta 和 Iceberg 客户端能够通过 Unity 目录和 Iceberg 目录 REST API 访问数据集，而无需完整数据复制。

管道数据集的外部数据访问适用于 Lakeflow Spark 声明性管道。

能力

对管道数据集使用外部数据访问可公开Azure Databricks中可用的相同数据，而无需创建数据的副本。这为性能和功能提供了以下特征：

无需复制数据： 未复制完整数据集，即可启用外部访问。
通过 API 进行外部访问： 使用 Delta Lake 或 Iceberg API 读取具体化视图和流式处理表。
写后读一致性： 在数据集更新后，外部读取方可以访问最新数据，确保不存在陈旧数据。刷新后即可立即获取更新。
单个表对象： 数据集在外部显示为 托管表 ，其名称与 Unity 目录 API 中的源数据集相同。
低成本： 由于未复制完整数据集，因此提供外部访问的开销较低。

Requirements

您的数据集需要满足以下要求：

必须为架构启用外部访问： 你的工作区必须已加入 管道数据集的外部数据访问公开预览，并且必须为包含你的数据集的架构启用此功能。请参阅启用对 Unity Catalog 数据的外部访问。
Unity Catalog：流式表和物化视图必须使用 Unity Catalog。
Databricks Runtime 版本： 必须使用 Databricks Runtime 17.3 及更高版本。

您的客户的要求如下：

Delta API 版本： 客户端必须支持 Delta Lake API 4.0.0 或更高版本（包括删除向量），并且必须使用 Unity Catalog 目录 API 进行访问。
Iceberg API 版本： 或者，客户端可以使用支持 Iceberg v3 规范的 Iceberg 目录 API 进行访问。
Unity Catalog 权限： 从外部读取数据集的主体必须对该架构具有 EXTERNAL USE SCHEMA 权限，并且对该表具有 SELECT 权限。

注意

如果客户端不支持这些要求，还可以使用兼容模式，该模式支持所有 Delta 和 Iceberg 客户端，但需要创建数据集的完整副本。

如何为数据集启用访问权限

可通过三个步骤为数据集启用外部访问。

在数据集定义中，添加以下内容 TBLPROPERTIES。这仅适用于 Iceberg v3 阅读器。如果只有 Delta 读取器，则可以跳过此步骤。

财产	使用
`'delta.columnMapping.mode' = 'name'`	Iceberg 必须使用列映射。
`'delta.universalFormat.enabledFormats' = 'iceberg'`	为 Iceberg 启用 UniForm。
`'delta.enableIcebergCompatV3' = 'true'`	将 Iceberg V3 用于 UniForm。
`'delta.enableChangeDataFeed' = 'false'`	变更数据馈送与外部访问不兼容，因此该项必须为 `false`。

例如，您可以通过在查询中添加以下 TBLPROPERTIES 来更新 Lakeflow Spark 声明式管道中的物化视图定义：

CREATE OR REFRESH MATERIALIZED VIEW view_name
  TBLPROPERTIES(
   ...
   'delta.columnMapping.mode' = 'name',
   'delta.enableIcebergCompatV3' = 'true',
   'delta.universalFormat.enabledFormats' = 'iceberg',
   'delta.enableChangeDataFeed' = 'false')
...

若要查看数据集的属性，可以使用 DESCRIBE EXTENDED SQL 语句。

将 Iceberg 属性应用于管道。这仅适用于 Iceberg v3 阅读器。如果只有 Delta 读取器，则可以跳过此步骤。
- 已触发的流水线：运行该流水线一次。
- 连续管道：停止并重启管道。
在管道配置中，将 pipelines.externalMetadata.enabled 设置为 true。

流水线设置界面
1. 打开管道，然后单击 “设置”。
2. 在 “配置”下，添加键值对：键pipelines.externalMetadata.enabled、值true。
3. 单击“ 保存”。
管道配置 JSON

在您的管道 JSON 的 configuration 部分中，添加：
```
{
  "configuration": {
    "pipelines.externalMetadata.enabled": "true"
  }
}
```
保存配置后，运行或重启管道以应用更改：
- 已触发的流水线：运行该流水线一次。
- 连续管道：停止并重启管道。

从外部客户端读取数据

以下部分介绍如何从不同的客户端和环境读取数据集。

将 Unity REST API 与 Spark 增量读取器配合使用

使用 Apache Spark™ 4.0 或更高版本。您可以从 https://spark.apache.org/downloads.html 下载。

根据云提供商，运行以下命令，使用 Delta 4.0 和 Unity 目录启动 Spark SQL shell。

蔚蓝

bin/spark-sql \
    --packages org.apache.hadoop:hadoop-azure:3.3.6,io.unitycatalog:unitycatalog-spark_2.13:0.3.1 \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

从 SQL shell 中，现在可以使用 Spark SQL 访问数据集。例如：
```
spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;
```

使用 Snowflake Iceberg 读取器

在 Snowflake 中，可以使用冰山阅读器。这需要支持 Iceberg v3，而 Snowflake 目前仅以私有预览形式提供此项支持。

在 Apache Spark 中设置 Iceberg REST 目录。

bin/spark-shell \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.8.0,org.apache.iceberg:iceberg-aws-bundle:1.8.0 \
  --conf "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" \
  --conf spark.sql.catalog.<uc-catalog-name>=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.<uc-catalog-name>.type=rest \
  --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace-url>/api/2.1/unity-catalog/iceberg-rest \
  --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
  --conf spark.sql.catalog.<uc-catalog-name>.warehouse=<uc-catalog-name>

在 Snowflake 中设置 Iceberg REST 目录。

CREATE OR REPLACE CATALOG INTEGRATION my_uc_int
  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'
    CATALOG_NAME = '<uc-catalog-name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<PAT>'
  )
  ENABLED = TRUE;

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = 'my_uc_int'
  CATALOG_TABLE_NAME = '<uc-table-name>';

从 Spark SQL 访问数据集。

spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;

从兼容性模式迁移

如果当前正在使用兼容模式共享数据集，则可以迁移到使用外部数据访问。

按照 “如何为数据集启用访问权限”中的步骤启用此功能。
禁用兼容性模式。请参阅 “禁用兼容性模式”

局限性

以下是有关流式表和物化视图的外部数据访问的已知限制。

外部写入： 不支持向管道数据集进行外部写入。
Path-Based Access： 不支持需要基于路径的访问的外部读取器（直接通过存储位置读取而不是 UC API 接口）。若要支持基于路径的访问，可以使用兼容模式，该模式支持基于路径的访问，但需要数据集的完整副本。
安全功能：不支持通过外部读取应用行级安全性或列级掩码。
时间旅行或 CDF： 不支持通过此功能支持 时间旅行 或更改 数据馈送（CDF ）。启用 UniForm Iceberg 时，必须禁用 CDF。
目录提交（测试版）：目录提交与外部数据访问不兼容。若要在流式表上使用外部数据访问，必须先禁用目录提交功能。目录提交操作不支持物化视图。
引入管道： 使用 Lakeflow Connect 创建的流式处理表不支持启用 Iceberg 表属性，并且仅适用于 Delta 读取器。
Fabric: 不支持从 Microsoft Fabric 中读取数据。
雪花冰山读者： 必须使用 Snowflake （个人预览版）中的 Iceberg v3 读取器来读取管道数据集。
独立 MV 和 ST： 此功能仅支持由管道管理的物化视图和流式表。不支持独立物化视图和流式表。如果您需要为独立物化视图和流式表提供外部访问权限，请联系 Databricks 账户团队。

Last updated on 2026-06-18