# Iceberg Tables

Iceberg Tables expose existing Apache Iceberg datasets from a connected [bucket](/docs/lakehouse/buckets.md). Use them when another system already owns the Iceberg table metadata and data files, and Altertable should query those tables without copying them.

Each mapping gives Altertable a logical table name and the Iceberg table path in the bucket. Altertable reads the Iceberg metadata to resolve snapshots, manifests, and data files.

## When to use Iceberg Tables

Use Iceberg Tables when:

- The dataset is already stored as Apache Iceberg in object storage.
- You know the bucket and path for each table you want to expose.
- Another engine or pipeline remains responsible for writing the Iceberg tables.

Use [Bucket Tables](/docs/lakehouse/external-catalogs/bucket-tables.md) for plain Parquet, CSV, or JSON files that are not managed by Iceberg metadata.

## Connect Iceberg Tables

1. Open **Catalogs** in the Altertable app.
2. Click **New catalog**.
3. Select **Iceberg Tables**.
4. Choose the connected bucket that stores the Iceberg datasets.
5. Add one or more table mappings with a table name and Iceberg table path.
6. Save the catalog, then query the mapped tables with SQL.

## Table mappings

| Field      | Description                                           | Example             |
| ---------- | ----------------------------------------------------- | ------------------- |
| Table name | The table name exposed in Altertable                  | `orders`            |
| Path       | The Iceberg table root or metadata path in the bucket | `warehouse/orders/` |

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