目录提交

目录提交将提交协调工作从文件系统转移到 Unity Catalog，使其成为 Delta Lake 和 Apache Iceberg 表状态的唯一可信来源。这样就可以支持多表事务、更快的查询规划，以及跨所有表操作的受管控访问。

传统的 Delta Lake 事务在单个表级别上协调提交。每个表单独管理自己的事务日志和冲突检测。通过将提交协调移动到目录级别，这样组织就可以一致地通过 Unity 目录管理对 Lakehouse 的所有访问。它还允许 Unity 目录协调单个事务边界内多个表的提交，同时维护 Delta Lake 的 ACID 保证。

Benefits

目录提交提供以下功能：

受管理的访问权限：读取和写入通过 Unity Catalog 目录进行协调，因此引擎能够看到最新的已提交状态，并应用治理策略。
更快的查询规划和写入：Unity 目录在访问表时直接通知 Delta 客户端表级元数据，跳过云存储并删除元数据延迟的主要源。
可强制约束：Unity 目录验证或拒绝架构和约束更改，防止可能会破坏数据完整性或下游工作负荷的不兼容更新。

Requirements

表必须是 Unity 目录管理的表（Delta 或 Iceberg），包括流表或实体化视图。
读取、写入或创建启用了 catalog commit 的托管表时，必须使用 Databricks Runtime 16.4 或更高版本。
要在现有托管表上启用或禁用目录提交功能，需要使用 Databricks Runtime 18.0 或更高版本。
必须使用 Databricks Runtime 17.3 及更高版本，才能读取或写入已启用目录提交的流式表或物化视图。
在 Spark 声明式管道中，若要对已启用目录提交的流式表或物化视图进行读取、写入、创建或升级，则必须使用无服务器计算，或使用 Databricks Runtime 17.3 及以上版本的经典计算。
要对现有流式表或具体化视图禁用目录提交，需要使用 Databricks Runtime 18 LTS 或更高版本。

启用目录提交

为新的或现有的托管表、流式表和物化视图启用目录提交功能。

为新的托管表启用目录提交

创建托管表时使用 delta.feature.catalogManaged 表属性：

CREATE TABLE sales_data (
  sale_id BIGINT,
  amount DECIMAL(10,2),
  sale_date DATE
)
TBLPROPERTIES ('delta.feature.catalogManaged' = 'supported');

为现有托管表启用目录提交

使用 ALTER TABLE 将目录提交添加到现有托管表中：

ALTER TABLE sales_data SET TBLPROPERTIES ('delta.feature.catalogManaged' = 'supported');

Important

在现有表上启用目录提交会将表状态与目录同步。对于具有大量写入操作的表，此操作可能需要几分钟时间。

为新的或现有的流式表或物化视图启用目录提交功能

在流式表或实体化视图定义中添加 delta.feature.catalogManaged 表属性，然后运行更新。对于已有的对象，更新其原始定义。不支持 ALTER TABLE ... SET TBLPROPERTIES。

以下示例使新流表或现有流表的目录提交成为可能：

CREATE OR REFRESH STREAMING TABLE streaming_sales_data
TBLPROPERTIES ('delta.feature.catalogManaged' = 'supported')
AS SELECT * FROM STREAM sales_data;

对于具体化视图，在定义中使用相同的表属性 CREATE OR REFRESH MATERIALIZED VIEW 。

检查是否启用了目录提交

若要验证表是否已启用目录提交，请执行以下操作：

DESCRIBE DETAIL sales_data;

如果已启用， catalogManaged 则显示在 tableFeatures 列中。

关闭目录提交

使用 Databricks Runtime 18.0 及更高版本，在现有托管表上禁用目录提交功能。

对于现有的流式表或物化视图，请使用 Databricks Runtime 18 LTS 或更高版本。

请参阅删除 Delta Lake 表功能并降级表协议。

警告

请勿在执行 ALTER 或 DROP 语句时取消升级或降级操作。中断可能会使该表处于部分升级或降级的状态，导致其此后无法进行任何读写操作。若要还原，请再次运行相应的命令，而不是取消。如果表被锁定，请联系 Databricks 支持部门。

Limitations

你不能使用 CREATE OR REPLACE TABLE 或 REPLACE TABLE 在现有托管表上启用或禁用目录提交。创建托管表时，使用 CREATE TABLE 和 delta.feature.catalogManaged 属性启用该功能；对于现有托管表，使用 ALTER TABLE 启用或禁用该功能。
目录提交与流式表或物化视图上的外部数据访问不兼容。若要使用目录提交，必须先禁用外部访问。请参阅为流式表和物化视图启用外部数据访问。
启用了目录提交的表通过 OpenSharing 共享时，使用预签名 URL 而非云令牌。
单用户群集无法访问启用了目录提交功能的流式表。

其他资源

Last updated on 2026-09-03