兼容性模式

2025-10-23

重要

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

使用兼容性模式，您可以从外部系统读取 Unity Catalog 托管表、物化视图和流式表，同时在 Azure Databricks 上保持优化的性能表现。此功能会自动生成您的表格的只读版本，任何 Delta Lake 或 Iceberg 客户端均可访问。

概述

在托管表、流式处理表或具体化视图上启用时，兼容性模式会在所选位置生成表的只读版本。此兼容性版本包括 Delta Lake 和 Iceberg 格式的 v1 元数据，提供以下功能：

与任何 Delta Lake 客户端的互操作性：从 Amazon Athena、Microsoft Fabric、Snowflake 和 Amazon Redshift 等客户端直接读取托管表，包括流式表或物化视图，直接从存储或通过 Unity REST API 读取。
与任何 Iceberg 客户端的互作性：通过 Iceberg REST 目录从 Iceberg 客户端（如 Apache Spark、Apache Trino 和 Snowflake）读取托管表（包括流式处理表或具体化视图）
免维护自动化：自动化刷新兼容性版本的数据和元数据，并能将刷新间隔配置到接近实时

先决条件

若要在表上启用兼容性模式，必须使用 Unity 目录。仅支持 Unity Catalog 流处理表、Unity Catalog 具体化视图和 Unity Catalog 管理表。不支持 Unity Catalog 的外部表。

此外，请验证是否在 Unity Catalog 中注册了外部位置，并确保其具有适当的设置和权限。

目标位置必须存在于存储帐户中，并且为空。
目标位置或其任何父文件夹必须在 Unity 目录中注册为外部位置。
必须具有 CREATE EXTERNAL TABLE 外部位置的权限。
目标位置和任何父文件夹或子文件夹不得在过去 7 天内用作另一个表的兼容模式位置。

在表上启用兼容性模式

对于流式处理表、具体化视图和管理的浅克隆，请在创建表时设置以下表属性：

CREATE [STREAMING TABLE | MATERIALIZED VIEW | TABLE] my_catalog.my_schema.my_table
TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>'
)

仅对于 Unity 目录托管表，还可以在更改现有表时启用兼容性模式：

-- For existing managed tables
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>'
)

首次生成兼容性版本最多需要一小时。可以立即手动刷新表，以确认它是否正常工作。

注释

必须指定完整的三部分表名称（catalog.schema.table_name）。例如，对于users.john.my_table，users是目录，john是架构。

检查是否启用了兼容性模式

若要验证是否在表上启用了兼容性模式，请检查 delta.universalFormat.enabledFormats = 'compatibility' 表属性是否存在。可以在您的表的详细信息选项卡中查看目录浏览器用户界面中的此属性。

还可以在笔记本中运行以下 SQL 命令：

DESC DETAIL my_catalog.my_schema.my_table
DESC EXTENDED my_catalog.my_schema.my_table

在输出中查找这些属性：

delta.universalFormat.enabledFormats: "compatibility" – 指示已启用兼容性模式
delta.universalFormat.compatibility.location – 显示兼容模式版本的位置

配置刷新间隔

对于 Unity 目录托管表，可以通过设置刷新间隔来配置兼容性模式版本刷新的频率：

-- Evaluate whether a refresh is needed after every commit (fastest)
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>',
  'delta.universalFormat.compatibility.targetRefreshInterval' = '0 MINUTES'
)

-- Refresh hourly (default)
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>',
  'delta.universalFormat.compatibility.targetRefreshInterval' = '1 HOUR'
)

默认刷新间隔为 1 HOUR。建议不要将刷新间隔设置为低于 1 小时，也不会使刷新更频繁地进行。例外情况是将刷新间隔设置为 0 MINUTES。在这种情况下，Azure Databricks 会在每次提交后检查更改，并根据需要触发刷新。

对于流式处理表和具体化视图，不需要刷新间隔。默认值为 0 MINUTES。

注释

无论目标刷新间隔如何，都会每小时执行影响刷新时间（例如列重命名或启用类型扩大）的更改。

手动刷新

手动触发兼容性版本的刷新：

REFRESH [TABLE | STREAMING TABLE | MATERIALIZED VIEW] my_catalog.my_schema.my_table SYNC UNIFORM

手动刷新可用于测试兼容模式是否正常工作，或在后续读取之前确保兼容版本是最新的。但是，等待自动刷新可能更具成本效益。

监视数据和元数据生成状态

兼容性模式会自动和异步生成数据和元数据。对于 Unity 目录托管表，默认情况下或基于配置的刷新间隔每小时生成一次。对于流式处理表和具体化视图，当有新提交时，在表更新后生成。

检查是否已成功生成数据和元数据：

使用DESCRIBE HISTORY查找源表的最新版本。
```
DESC HISTORY my_catalog.my_schema.my_table
```
此命令将刷新历史记录返回到兼容模式，包括 Delta Lake 版本和时间戳。顶部行包含最新版本和时间戳。
使用 DESCRIBE EXTENDED 查找相应的兼容模式版本：
```
DESC EXTENDED my_catalog.my_schema.my_table
```
在 统一兼容性信息下查找字段：
- 上次刷新的版本：上次使用兼容性模式更新的 Delta Lake 版本
- 上次刷新：上次刷新的时间戳
如果表版本与步骤 1 中找到的版本匹配，那么兼容性模式是最新的。
请在兼容性版本本身上使用 DESC HISTORY。
```
DESC HISTORY delta.\`<compatibility_location>\`
```
在目录资源管理器中，查看兼容性版本的元数据字段。如果 Delta Lake 版本与步骤 3 中找到的版本匹配，则兼容性模式是最新的。

监控成本

预测优化处理执行兼容性模式自动刷新的计算群集。若要查看关联的成本，请查询系统计费表：

SELECT
  DATE_TRUNC('DAY', start_time) AS day,
  SUM(usage_quantity) AS dbus
FROM
  system.storage.predictive_optimization_operations_history
WHERE
  operation_type = "COMPATIBILITY_MODE_REFRESH"
GROUP BY 1
ORDER BY 1 DESC;

此查询仅报告自动刷新的使用情况。手动刷新的成本与计算相关联，并且没有直接方法可以单独跟踪这些成本。通常，手动触发器的成本与初始写入操作到原表的成本成正比。

删除未使用的数据文件

若要删除表兼容性版本的未使用的数据文件，请使用 VACUUM：

VACUUM delta.'<compatibility_mode_location_path>';

若要查找兼容性模式位置路径，请使用DESCRIBE EXTENDED“检查是否启用了兼容性模式”中的命令。在输出中，delta.universalFormat.compatibility.location 的值为位置。

从外部客户端读取兼容性版本

可以使用任何 Delta Lake 或 Iceberg 客户端从兼容性版本读取数据。有关 Amazon Athena、Snowflake （Delta reader）和 Fabric 的示例，请参阅下文。

Amazon Athena

在 Athena 查询编辑器中，创建具有指定位置的外部表：

CREATE EXTERNAL TABLE <table_name>
LOCATION '<compatibility_location>'
TBLPROPERTIES ('table_type' = 'DELTA')

阅读表：
```
SELECT * FROM <table_name>
```

Snowflake Delta Lake 阅读器

创建存储集成以访问存储位置（请参阅 Snowflake 文档）。

使用 Delta Lake 格式创建外部表：

CREATE OR REPLACE EXTERNAL TABLE <table_name>
WITH LOCATION = @<my_location>
FILE_FORMAT = (TYPE = PARQUET)
TABLE_FORMAT = DELTA
AUTO_REFRESH = false
REFRESH_ON_CREATE = false;

刷新表（Snowflake 中的 Delta Lake 格式不支持自动刷新）：
```
ALTER EXTERNAL TABLE <table_name> REFRESH;
```
读取表：
```
SELECT * FROM <table_name>;
```

Microsoft Fabric

创建 Fabric 容量、工作区和 Synapse 笔记本。
在兼容位置创建数据湖仓。

以 Delta Lake 表的形式读取文件：

spark.read.format("delta").load("Files/<path_to_data>")

从 Unity REST API 读取兼容性版本

启用了兼容性模式的表可以通过具有特殊参数的 Unity REST API 按名称读取。对于流式处理表，请设置以下 API 参数：

GET /api/2.1/unity-catalog/tables/{full_name}?read_streaming_table_as_managed=true

对于具体化视图，请设置以下 API 参数：

GET /api/2.1/unity-catalog/tables/{full_name}?read_materialized_view_as_managed=true

从 Iceberg REST 目录读取兼容性版本

可以使用 Iceberg REST 目录从任何 Iceberg 客户端读取启用了兼容性模式的表。兼容性模式自动适用于 Delta Lake 和 Iceberg 表格式。

设置要求

在元存储上启用外部数据访问。
授予 EXTERNAL USE SCHEMA 对架构的权限。
创建 Azure Databricks 个人访问令牌（PAT）。

Apache Spark 配置

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

有关详细信息，请参阅将 Iceberg 表与 Apache Spark 配合使用。

Snowflake 配置

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-st/mv-name>';

禁用兼容性模式

若要禁用兼容性模式，请取消设置相应的表属性：

-- For UC managed tables
ALTER TABLE my_table UNSET TBLPROPERTIES('delta.universalFormat.enabledFormats')

-- For streaming tables and materialized views
CREATE OR REPLACE [STREAMING TABLE | MATERIALIZED VIEW] my_table
TBLPROPERTIES('delta.universalFormat.enabledFormats' = '')

警告

取消设置兼容性模式会立即停止数据和元数据生成。 7 天后，将删除关联的数据和元数据。在此 7 天内，可以通过在同一个表上重新启用兼容性模式来还原数据和元数据。

局限性

只读访问：兼容性版本为只读。无法写入兼容性版本。
不支持 RLS/CLS：不能对具有 Row-Level 安全（RLS）或 Column-Level 安全性（CLS）的表启用兼容性模式。
没有分区列重命名：启用了兼容性模式的表不支持分区列重命名。支持数据列重命名。
有限的表功能：兼容性版本中不提供以下功能：
- 排序规则列
- 主键
- 按时间顺序查看
- 更改数据流
- 具有特殊字符的列名（将重命名）

反馈

此页面是否有帮助？