# Query with DuckDB

The [DuckDB Altertable extension](https://github.com/altertable-ai/duckdb-altertable) 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={{LAKEHOUSE_USERNAME}} password={{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 '{{LAKEHOUSE_USERNAME}}',
  PASSWORD '{{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](/docs/query-data/pandas-polars-ibis.md). For ingesting data from DuckDB, see [Ingest data with DuckDB](/docs/ingest-data/duckdb.md). For more examples and source builds, see the [DuckDB Altertable extension repository](https://github.com/altertable-ai/duckdb-altertable).