DuckDB

Query with DuckDB

The DuckDB Altertable extension connects DuckDB to Altertable. Use it when you want to query governed Altertable data from DuckDB or join it with local files.

The extension supports:

Attached databases for querying Altertable catalogs with standard SQL
Direct table access through DuckDB's catalog
Raw query execution for remote SQL statements

Installation

Install and load the community extension from DuckDB:

SQL

INSTALL altertable FROM community;
LOAD altertable;

Attach a database

Use your lakehouse username, lakehouse password, and catalog in the connection string:

SQL

ATTACH
'user=YOUR_LAKEHOUSE_USERNAME password=YOUR_LAKEHOUSE_PASSWORD catalog=your-lakehouse-catalog'
AS remote_db (TYPE ALTERTABLE);

Connection parameters

Parameter	Description	Example
`user`	Lakehouse username	`your_lakehouse_username`
`password`	Lakehouse password	`your_lakehouse_password`
`catalog`	Remote Altertable catalog	`analytics`

Or use DuckDB secrets:

SQL

CREATE SECRET my_altertable (
  TYPE altertable,
  USER 'YOUR_LAKEHOUSE_USERNAME',
  PASSWORD 'YOUR_LAKEHOUSE_PASSWORD',
  CATALOG 'your-lakehouse-catalog'
);

ATTACH '' AS remote_db (TYPE altertable, SECRET my_altertable);

To disconnect the attached catalog:

SQL

DETACH remote_db;

Query a remote table

Query tables through the attached Altertable database:

SQL

SELECT * FROM remote_db.main.orders;

Filter results

Run SELECT queries against attached Altertable tables:

SQL

SELECT order_id, amount, status
FROM remote_db.main.orders
WHERE status = 'open';

Export to local files

Export attached tables to local files:

SQL

COPY remote_db.main.orders TO 'orders.csv';
COPY remote_db.main.orders TO 'orders.parquet';
COPY remote_db.main.orders TO 'orders.json';

For Python DataFrame workflows, see Query with Pandas, Polars, and Ibis. For ingesting data from DuckDB, see Ingest data with DuckDB. For more examples and source builds, see the DuckDB Altertable extension repository.