---
title: Use DuckDB with Unity Catalog
summary: Attach a Unity Catalog catalog in DuckDB, query its Delta tables with
  SQL, and append rows.
diataxis: how-to
project: unitycatalog
canonical: https://docs.unitycatalog.io/how-to/duckdb
companions:
  - url: "https://docs.unitycatalog.io/how-to/duckdb/snippets/duckdb_tables.py"
    kind: python
    purpose: "Read and append to a Unity Catalog managed Delta table from DuckDB."
    run: "UNITY_CATALOG_URL=http://localhost:8080/api/2.1/unity-catalog uv run https://docs.unitycatalog.io/how-to/duckdb/snippets/duckdb_tables.py"
    requires-python: ">=3.11"
    services: ["unitycatalog"]
environment:
  title: "Unity Catalog 0.7.0"
  dir: "uc-docs-env/unitycatalog"
  start: ["curl -fsSL https://docs.unitycatalog.io/env/unitycatalog.tar.gz | tar -xz", "cd uc-docs-env/unitycatalog && docker compose up -d --wait", "export UNITY_CATALOG_URL=http://localhost:8080/api/2.1/unity-catalog"]
  stop: "docker compose down"
  elements: ["unityCatalogOSS"]
  index: "https://docs.unitycatalog.io/env/environments.json"
---

## Companion files

CI-tested scripts that run this page's examples end to end. A script that exits 0 has passed its checks.

They need Unity Catalog 0.7.0 running. To start it (also `environment` in this file's frontmatter):

```bash
curl -fsSL https://docs.unitycatalog.io/env/unitycatalog.tar.gz | tar -xz
cd uc-docs-env/unitycatalog && docker compose up -d --wait
export UNITY_CATALOG_URL=http://localhost:8080/api/2.1/unity-catalog
```

- [`duckdb_tables.py`](https://docs.unitycatalog.io/how-to/duckdb/snippets/duckdb_tables.py) (Python): Read and append to a Unity Catalog managed Delta table from DuckDB.
  - run: `UNITY_CATALOG_URL=http://localhost:8080/api/2.1/unity-catalog uv run https://docs.unitycatalog.io/how-to/duckdb/snippets/duckdb_tables.py`

DuckDB queries [Unity Catalog](https://docs.unitycatalog.io/explanation/what-is-unity-catalog "The open-source reference server implementing the Unity Catalog specification.") tables with SQL and appends rows to them, including catalog-managed Delta tables. DuckDB's `unity_catalog` extension attaches a catalog as a DuckDB database, and its `delta` extension reads and writes the [Delta](https://delta.io "Open table-format specification: ACID transactions, schema evolution, and time travel over object storage.") files. Appends to a catalog-managed table go through the server, like a Spark write.

> **Prerequisites**
>
> - [Docker](https://docs.docker.com/get-started/get-docker/) with Compose v2, for the local environment.
> - Unity Catalog 0.7.0, running: [Run a local Unity Catalog server](https://docs.unitycatalog.io/how-to/run-local-server).
> - A Delta table in Unity Catalog, such as `retail.sales.orders` from [Create and update a catalog-managed Delta table](https://docs.unitycatalog.io/tutorials/managed-delta-table).
> - Table files that DuckDB can reach, such as the local server's [shared folder](https://docs.unitycatalog.io/how-to/run-local-server#share-a-folder-with-the-server).
> - [uv](https://docs.astral.sh/uv/getting-started/installation/).

## Install the extensions

Open a Python session with DuckDB:

```bash
uv run --with duckdb==1.5.6 python
```

Install and load `delta`, then `unity_catalog` from DuckDB's `core_nightly` channel:

`duckdb_tables.py`

```python
import duckdb

con = duckdb.connect()
con.execute("INSTALL delta")
con.execute("LOAD delta")
con.execute("FORCE INSTALL unity_catalog FROM core_nightly")
con.execute("LOAD unity_catalog")
```

## Attach a catalog

Create a secret that holds the server's address and a token, then attach one Unity Catalog catalog as a DuckDB database:

`duckdb_tables.py`

```python
con.execute("""
    CREATE SECRET (
        TYPE unity_catalog,
        TOKEN 'not-used',
        ENDPOINT 'http://localhost:8080'
    )
""")
con.execute("ATTACH 'retail' AS retail (TYPE unity_catalog, DEFAULT_SCHEMA 'sales')")
```

- `ENDPOINT` is the server's base URL, without `/api/2.1/unity-catalog`.
- `TOKEN` is sent as a bearer token. The local server has authorization disabled and accepts any value. On a secured server, use a Unity Catalog access token.
- `DEFAULT_SCHEMA` is the schema DuckDB uses for unqualified table names.

Leave the secret unnamed. With a named secret (`CREATE SECRET uc (...)`), `ATTACH` fails with `Could not resolve hostname`.

## List tables

`duckdb_tables.py`

```python
con.sql("SELECT database, schema, name FROM (SHOW ALL TABLES)").show()
```

```text
┌──────────┬─────────┬─────────┐
│ database │ schema  │  name   │
│ varchar  │ varchar │ varchar │
├──────────┼─────────┼─────────┤
│ retail   │ sales   │ orders  │
└──────────┴─────────┴─────────┘
```

## Query a table

Use three-part names, or just the table name for tables in the default schema:

`duckdb_tables.py`

```python
con.sql("""
    SELECT customer, amount
    FROM retail.sales.orders
    WHERE amount > 5
    ORDER BY order_id
""").show()
```

```text
┌──────────┬───────────────┐
│ customer │    amount     │
│ varchar  │ decimal(10,2) │
├──────────┼───────────────┤
│ ada      │          9.50 │
│ grace    │         20.00 │
└──────────┴───────────────┘
```

DuckDB asks the server for the table's location and for temporary credentials, then reads the Delta files directly from storage. For a catalog-managed table it reads the latest version the server has accepted. DuckDB reads tables with column mapping through Unity Catalog, too.

## Append rows

`INSERT` adds rows to the table:

`duckdb_tables.py`

```python
con.execute("INSERT INTO retail.sales.orders VALUES (4, 'barbara', 12.00)")
```

On a catalog-managed table, DuckDB writes the new data and commit file, then asks the server to accept the commit as the table's next version. From then on, Spark and every other client see the new rows.

DuckDB can't append to a partitioned table that uses column mapping. The insert fails with `Not implemented Error: Inserting into a partitioned Delta table that uses column mapping is not supported`, and the table doesn't change.

## Create, change, and drop tables

DuckDB reads tables and appends rows. Create tables with Spark. Update, delete from, and drop them with Spark too, as in [Create and update a catalog-managed Delta table](https://docs.unitycatalog.io/tutorials/managed-delta-table).

## Required privileges

With authorization enabled, reading needs `USE CATALOG` on the catalog, `USE SCHEMA` on the schema, and `SELECT` on the table. Appending also needs `MODIFY` on the table. Owners have all of these. See [Core concepts](https://docs.unitycatalog.io/explanation/uc-basics#ownership-and-privileges).

## Next steps

- [External tables and catalog-managed Delta tables](https://docs.unitycatalog.io/explanation/external-and-managed-tables) explains why an append from DuckDB is safe next to a Spark writer.
- [DuckDB's Unity Catalog extension documentation](https://duckdb.org/docs/stable/core_extensions/unity_catalog) covers its other secret options and cloud storage.