Skip to main content
Last updated on

Catalog-managed commits

This article explains how to enable catalog-managed commits, a Delta table feature that shifts transaction coordination from the filesystem to Unity Catalog, making the catalog the single source of truth for table state.

Overview​

Traditional Delta Lake transactions coordinate commits at the individual table level. Each table manages its own transaction log and conflict detection independently. Catalog-managed commits move this coordination to the catalog level. This allows organizations to consistently govern all access to the lakehouse through Unity Catalog, preventing ungoverned path-based access. It also allows Unity Catalog to orchestrate commits across multiple tables within a single transaction boundary while maintaining Delta Lake's ACID guarantees.

Requirements​

  • Tables must be Unity Catalog managed tables.
  • Databricks Runtime 16.4 and above is required to read from, write to, or create tables with catalog-managed commits enabled.
  • Databricks Runtime 18.0 and above is required to enable or disable catalog-managed commits on existing tables.

Enable catalog-managed commits​

You can enable catalog-managed commits on new and existing tables.

Enable catalog-managed commits for new tables​

Use the delta.feature.catalogManaged table property when creating a table:

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

Enable catalog-managed commits for existing tables​

Use ALTER TABLE to add catalog-managed commits to an existing table:

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

Enabling catalog-managed commits requires a metadata-only transaction to synchronize table state with the catalog. This transaction can take several minutes for large tables. Concurrent writes are allowed during synchronization, but Databricks might retry or cancel them if conflicts cannot be automatically resolved.

Check if catalog-managed commits are enabled​

To verify whether a table has catalog-managed commits enabled:

SQL
DESCRIBE DETAIL sales_data;

If enabled, catalogManaged appears in the tableFeatures column.

Disable catalog-managed commits​

You can disable catalog-managed commits using Databricks Runtime 18.0 or above. See Drop a Delta Lake table feature and downgrade table protocol.

warning

Do not cancel upgrade or downgrade operations while executing ALTER or DROP statements. Interruption can leave the table in a partially upgraded or downgraded state, locking it from all future reads and writes. To revert, run the appropriate command again rather than canceling. Contact Databricks support if the table becomes locked.

Limitations​

  • CREATE OR REPLACE TABLE is not supported for tables with catalog-managed commits enabled.

Next steps​