# DuckDB

DuckDB external catalogs expose an existing `.duckdb` database file that already lives in a connected bucket. Use this when another process produces a DuckDB database and you want to query it from Altertable without importing it into an Altertable catalog.

## Requirements

- A [bucket](/docs/lakehouse/buckets.md) connected to the environment
- A DuckDB database file stored in that bucket
- A path ending in `.duckdb`

DuckDB catalogs are read-only in Altertable.

## Connect a DuckDB Catalog

1. Open **Catalogs** in the target environment.
2. Click **New catalog** and choose **DuckDB**.
3. Select the bucket that contains the DuckDB file.
4. Enter the path to the `.duckdb` file, such as `exports/reporting.duckdb`.
5. Test and create the catalog.

After the catalog is created, its schemas and tables appear in the catalog browser and can be queried with SQL.

## Query Example

```sql
SELECT
  customer_id,
  total_revenue
FROM reporting_duckdb.main.customer_revenue
ORDER BY total_revenue DESC
LIMIT 25;
```

You can join DuckDB catalog tables with Altertable catalogs and other external catalogs in the same query.

## When to Use an Altertable Catalog Instead

Use an [Altertable catalog](/docs/lakehouse.md) when Altertable should own the storage layout, snapshots, writes, and retention. Use a DuckDB external catalog when the `.duckdb` file is produced elsewhere and Altertable only needs read access.