The unity_catalog extension attaches a Unity Catalog catalog, on Databricks or Unity Catalog OSS, as a DuckDB database. You can list, read, insert into and create its Delta Lake tables. It uses the delta extension to access the tables.

For implementation details, see the “Delta Grows Up: Writes, Unity Catalog and Time Travel” blog post.

Note Both extensions are available on a subset of platforms.

Installing and Loading

The unity_catalog extension will be transparently autoloaded on first use from the official extension repository. It loads the delta extension itself. If you would like to install and load it manually, run:

INSTALL AND LOAD unity_catalog;

Usage

To connect to Unity Catalog on Databricks or Unity Catalog OSS, create a secret with your token, endpoint and region, then attach a catalog:

CREATE SECRET (
    TYPE unity_catalog,
    TOKEN 'token',
    ENDPOINT 'endpoint',
    AWS_REGION 'region'
);
ATTACH 'catalog_name' AS my_catalog (TYPE unity_catalog, DEFAULT_SCHEMA 'main');

• ENDPOINT is the Unity Catalog REST API endpoint. For Databricks, it is your Workspace URL, typically https://instance.cloud.databricks.com/.
• TOKEN is a credential. For Databricks, it can be a personal access token with unity-catalog scope; see Access Control in Unity Catalog for the other options. For Unity Catalog OSS, see the OSS Unity Catalog documentation.
• AWS_REGION is the region of the storage that holds the tables. It is required.

To read and write the table files, DuckDB also needs a secret for that storage, e.g., an S3 secret or an Azure secret.

Note Only Databricks reports a default namespace. When you attach a Unity Catalog OSS catalog, always set DEFAULT_SCHEMA: without it, queries against the catalog fail, even with fully qualified table names.

Attach Options

When attaching a Unity Catalog catalog, you can pass the following options to ATTACH:

Reading

Tables are named catalog.schema.table; names without a schema resolve to DEFAULT_SCHEMA:

SHOW ALL TABLES;
SELECT * FROM my_catalog.my_schema.my_table LIMIT 10;

Time Travel

New Time travel by timestamp was introduced in DuckDB 2.0.

To read a table as of a version or a point in time, use the AT clause:

SELECT * FROM my_catalog.my_schema.my_table AT (VERSION => 5);
SELECT * FROM my_catalog.my_schema.my_table AT (TIMESTAMP => TIMESTAMPTZ '2026-10-01 12:00:00+00');

A timestamp reads the latest version committed at or before that time. A timestamp before the table's first commit or later than the current time fails with an error.

Writing

To append rows, use INSERT INTO:

INSERT INTO my_catalog.my_schema.my_table VALUES (1, 'hello');
INSERT INTO my_catalog.my_schema.my_table SELECT * FROM other_table;

Data Types

Unity Catalog column types map to DuckDB types as follows. Since v1.5.6, DuckDB reads them from the table's Delta log.

• timestamp maps to TIMESTAMP WITH TIME ZONE and, since v1.5.6, timestamp_ntz to TIMESTAMP.
• Since v1.5.6, a column of a type that DuckDB cannot read is listed with the type UNKNOWN, e.g., in DESCRIBE. Reading the table fails with an error that names the column.

VARIANT Columns

New Support for VARIANT columns was introduced in DuckDB 2.0.

Unity Catalog's variant maps to VARIANT. VARIANT columns can be read whether their files are shredded or not. Inserts write shredded variants if the table sets delta.enableVariantShredding. An INSERT into a table with a VARIANT inside a struct, list or map fails with an error.

Creating Tables

New This feature was introduced in DuckDB 2.0.

CREATE TABLE in a Unity Catalog schema writes the first version of a new Delta table and registers the table with Unity Catalog.

Without a location, the table is a managed table: Unity Catalog chooses where it is stored, and the table uses catalog-managed commits:

CREATE TABLE my_catalog.my_schema.my_table (id INTEGER, name VARCHAR);

With the location option, the table is an external table at that location. The location can be any expression that evaluates to an absolute path or a URI:

CREATE TABLE my_catalog.my_schema.my_external_table (id INTEGER, name VARCHAR)
WITH (location = 's3://my_bucket/path');

Both managed and external tables can be partitioned:

CREATE TABLE my_catalog.my_schema.my_partitioned_table (id INTEGER, part VARCHAR)
PARTITIONED BY (part);

CREATE TABLE IF NOT EXISTS does nothing if Unity Catalog already has a table with this name.

For the forms and options that CREATE TABLE does not support, see Limitations.

Warning Unity Catalog registers the table while CREATE TABLE runs, so a ROLLBACK of the surrounding transaction does not remove the table.

Checkpointing

Since v1.5.1, unity_catalog_checkpoint_table compacts the Delta log of a table into a checkpoint file, which speeds up reads of tables with long logs. Pass the table name as a string, either fully qualified or relative to the catalog and schema set with USE:

CALL unity_catalog_checkpoint_table('my_catalog.my_schema.my_table');

The CHECKPOINT statement does not apply to Unity Catalog tables and fails with an error.

Server-Side Scan Planning

New This feature was introduced in DuckDB 2.0.

Databricks can plan scans on the server, through the Iceberg REST Catalog (IRC) API of Unity Catalog. The API uses catalog-wide statistics, which can improve filtering and reduce the number of files that a query scans. Unity Catalog OSS does not offer this API.

With USE_IRC_SCAN_PLAN true, DuckDB sends each scan's filters to the server and reads only the files that it returns, with their delete files. DuckDB still applies the filters itself:

ATTACH 'catalog_name' AS my_catalog (
    TYPE unity_catalog,
    DEFAULT_SCHEMA 'main',
    USE_IRC_SCAN_PLAN true
);

• If the server cannot plan a scan, e.g., because it does not offer the API or refuses the table, DuckDB reads the table through its Delta log instead, and does not try scan planning again on this attached catalog for 15 minutes.
• Time travel queries (AT (...)) always read through the Delta log.
• Positional delete files and deletion vectors are applied. A table with equality delete files fails with an error; to read it, attach the catalog without USE_IRC_SCAN_PLAN.

Catalog-Managed Commits

Managed tables in Databricks and in Unity Catalog OSS may use catalog-managed commits (Catalog-Coordinated Commits / CCv2), where Unity Catalog coordinates commits rather than writers committing directly to the Delta log. Since v1.5.2 (v1.5.5 for Unity Catalog OSS), DuckDB uses this protocol when the attached table requires it. INSERT statements are identical in syntax, but they commit through the catalog-managed write protocol, so Unity Catalog coordinates concurrent writers. For details, see the “Delta Grows Up: Writes, Unity Catalog and Time Travel” blog post.

A managed table that DuckDB creates uses catalog-managed commits. Tables created by other clients, e.g., Spark or the Unity Catalog CLI, are read and written the same way.

Features

This extension supports:

• Listing available tables: SHOW ALL TABLES;
• Interacting with tables using standard SQL: SELECT * FROM catalog.schema.table;
• Time travel: SELECT * FROM ... AT (VERSION => ...); and SELECT * FROM ... AT (TIMESTAMP => ...);
• Inserts: INSERT INTO ... VALUES (...);
• Creating managed and external tables: CREATE TABLE ... (...);
• Checkpointing individual tables (since v1.5.1): CALL unity_catalog_checkpoint_table('my_catalog.my_schema.my_table');

Limitations

• DELETE and UPDATE are not supported.
• DROP TABLE and ALTER TABLE are not supported, nor is creating or changing views or schemas.
• Inserts into a table with column DEFAULT values or generated columns fail with an error, as DuckDB cannot compute these columns yet.
• Reading a table with an INTERVAL column fails with an error, as Delta intervals and DuckDB's INTERVAL differ in meaning.
• The following CREATE TABLE forms and options are not supported and fail with an error:
  • CREATE OR REPLACE TABLE and CREATE TABLE ... AS SELECT
  • constraints, including NOT NULL and PRIMARY KEY
  • column DEFAULT values and generated columns
  • columns of a type that Delta cannot store, e.g., TIME
  • SORTED BY
  • WITH options other than location: unlike with the delta extension, Delta table properties cannot be set

Supported Platforms

The unity_catalog and delta extensions support the following platforms:

• Linux (x86_64 and ARM64): linux_amd64 and linux_arm64
• macOS Intel and Apple Silicon: osx_amd64 and osx_arm64
• Windows AMD64: windows_amd64

Support for the other DuckDB platforms is work-in-progress.