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 a managed catalog.

Requirements

• A bucket 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

Copy
1
2
3
4
5
6
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 managed Altertable catalogs and other external catalogs in the same query.

When to Use a Managed Catalog Instead

Use an Altertable catalog 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.