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

如果你 启用了对Unity Catalog的外部数据访问，可以为流水线管理的和独立的实体化视图和流表添加外部数据访问。 这使外部 Delta 和 Iceberg 客户端能够通过 Unity 目录和 Iceberg 目录 REST API 访问数据集，而无需完整数据复制。

外部数据访问可用于访问由 Lakeflow 管道管理的数据集，以及独立的物化视图和流式表。

能力

使用外部数据访问可以将Azure Databricks中相同的数据暴露给流水线管理和独立的实体化视图和流表，而无需创建数据的副本。 这为性能和功能提供了以下特征：

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

Requirements

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

  • Unity Catalog：流式表和物化视图必须使用 Unity Catalog。
  • Databricks Runtime 版本： 必须使用 Databricks Runtime 17.3 及更高版本。
  • 默认发布模式： 外部可读性仅支持默认发布模式。 要使用外部可读性，迁移 到默认发布模式。 依赖外部元数据的功能（例如物化视图 CDF）将在旧版发布模式下正常工作。

您的客户的要求如下：

  • 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 客户端，但需要创建数据集的完整副本。

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

启用数据集外部访问有两个步骤。

  1. 通过管道配置或表属性启用外部元数据。 当两者都已设置时，表级设置优先于流水线配置，并且支持流水线管理、独立流式表和实体化视图。

    • 管道配置： 设置为 pipelines.externalMetadata.enabledtrue 以启用流水线中所有数据集的外部元数据。 用Databricks SQL创建的独立实体化视图和流表没有流水线配置;改用表属性。

      流水线设置界面

      在流水线设置中，请完成以下步骤：

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

      管道配置 JSON

      在您的管道 JSON 的 configuration 部分中，添加：

      {
  "configuration": {
    "pipelines.externalMetadata.enabled": "true"
  }
}

    保存配置后，运行或重启管道以应用更改：

    • 已触发的流水线：运行该流水线一次。
    • 连续管道：停止并重启管道。

    对于独立的Databricks SQL对象，可以使用 CREATE OR REPLACE MATERIALIZED VIEW 或 CREATE OR REFRESH STREAMING TABLE 使用表属性。 创建或刷新语句应用该属性。

  2. 如果你打算用现代 Iceberg 客户端读取数据集，除了外部元数据属性外，还要添加以下 UniForm Iceberg V3 属性。

    财产 使用
    'pipelines.externalMetadata.enabled' = 'true' 启用桌面的外部访问权限。 当两者都已设置时，表级设置优先于管道配置。
    'delta.columnMapping.mode' = 'name' Iceberg 必须使用列映射。
    'delta.enableRowTracking' = 'true' 为 Iceberg 读取启用行跟踪。
    'delta.universalFormat.enabledFormats' = 'iceberg' 启用 Iceberg 读取功能。
    'delta.enableIcebergCompatV3' = 'true' 用 Iceberg V3 来读取 Iceberg。 
    CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableRowTracking' = 'true',
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg',
  'pipelines.externalMetadata.enabled' = 'true')

    对于物化视图，你可以改用等效的 USING ICEBERG 语法。

    CREATE OR REFRESH MATERIALIZED VIEW tbl_name USING ICEBERG

    对于流水线管理的数据集，请使用上述流水线更新指令应用Iceberg属性。 对于独立的Databricks SQL对象，请用更新后的属性重新运行对象定义。 对实体化视图使用 CREATE OR REPLACE MATERIALIZED VIEW，对流式表使用 CREATE OR REFRESH STREAMING TABLE。 要查看数据集的属性，可以使用 DESCRIBE DETAIL or DESCRIBE EXTENDED SQL 语句。

外部数据访问故障排除

如果你认为外部元数据已经过时，拥有 MODIFY 表权限的主体可以通过 Databricks 运行时 17.3 或更高版本手动触发共享集群计算中的元数据更新：

REPAIR TABLE <catalog>.<schema>.<table-name> SYNC METADATA;

你可以在 Catalog Explorer 界面的表详细信息页面上查看是否存在 Iceberg 元数据。 或者，在 SQL 编辑器或Azure Databricks笔记本中运行以下命令：

DESCRIBE DETAIL <catalog>.<schema>.<table-name>;
DESCRIBE EXTENDED <catalog>.<schema>.<table-name>;

对于流式表，可以比较 Iceberg 元数据版本与最新的流式表版本。 具体化视图的版本对比尚未可用。

从外部客户端读取数据

以下章节提供了如何从不同客户端和环境中读取数据集的示例。

有关设置细节，请参见 Delta客户端访问 和 Iceberg客户端访问。

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

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

  1. 根据云提供商，运行以下命令，使用 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>

  2. 从 SQL shell 中，现在可以使用 Spark SQL 访问数据集。 例如：

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

使用 Snowflake Iceberg 读取器

在 Snowflake 中，可以使用冰山阅读器。 这需要在 Snowflake 中支持 Iceberg v3。

  1. 在 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>';

  2. 从Snowflake SQL访问你的数据集。

    ALTER ICEBERG TABLE my_table REFRESH;
SELECT * FROM my_table;

将 Iceberg REST 目录与 Spark Iceberg 阅读器配合使用

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

  1. 在 AWS 中运行以下命令，使用 Iceberg v3 启动 Spark SQL shell。

    bin/spark-sql \
  --packages org.apache.iceberg:iceberg-spark-runtime-4.0_2.13:1.10.0,org.apache.iceberg:iceberg-aws-bundle:1.10.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>.io-impl=org.apache.iceberg.aws.s3.S3FileIO \
  --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> \
  --conf spark.sql.iceberg.vectorization.enabled=false

  2. 从 Spark SQL 访问数据集。

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

从兼容性模式迁移

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

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

局限性

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

  • 外部写入： 不支持向管道数据集进行外部写入。
  • Path-Based Access： 不支持需要基于路径的访问的外部读取器（直接通过存储位置读取而不是 UC API 接口）。 若要支持基于路径的访问，可以使用 兼容模式，该模式支持基于路径的访问，但需要数据集的完整副本。
  • 安全功能：不支持通过外部读取应用行级安全性或列级掩码。
  • 时间旅行：不支持通过此功能进行时间旅行。
  • 目录提交（测试版）：目录提交与外部数据访问不兼容。 要在流式表或物化视图上使用外部数据访问，必须先禁用目录提交功能。
  • Last updated on