# Bucket Tables

Bucket Tables expose files from a connected [bucket](/docs/lakehouse/buckets.md) as queryable external tables. Use them when Parquet, CSV, or JSON files already exist in object storage and you want to query them without copying the data into an Altertable catalog.

Each table maps a logical table name to a path in the bucket. Queries read the files at that path through the lakehouse SQL engine.

## When to use Bucket Tables

Use Bucket Tables for:

- Data exports that already land in object storage.
- Shared Parquet datasets owned by another pipeline.
- CSV or JSON files that need to be joined with other lakehouse sources.
- Hive-style partitioned paths where partition keys should be available as columns.

If the files are an Iceberg dataset, use [Iceberg Tables](/docs/lakehouse/external-catalogs/iceberg-tables.md) instead so Altertable can read Iceberg metadata.

## Connect Bucket Tables

1. Open **Catalogs** in the Altertable app.
2. Click **New catalog**.
3. Select **Bucket Tables**.
4. Choose the connected bucket that contains the files.
5. Select the file format: Parquet, CSV, or JSON.
6. Add one or more table mappings with a table name and path.
7. Save the catalog, then query the mapped tables with SQL.

## Table mappings

Use stable, descriptive table names and point each one at the file or prefix Altertable should read:

| Field      | Description                                         | Example           |
| ---------- | --------------------------------------------------- | ----------------- |
| Table name | The table name exposed in the external catalog      | `events`          |
| Path       | The file path or prefix inside the connected bucket | `exports/events/` |

After the catalog is connected, query tables with fully qualified names such as `bucket_exports.main.events`.