# Lakehouse

A lakehouse separates stateless compute from infinitely scalable object storage: compute can start, stop, and scale independently while data remains durable in buckets. Altertable Lakehouse builds on that model with catalogs that define what you query, Workers that run SQL, Buckets that store table files in object storage, and external catalogs that connect existing databases, warehouses, and file-backed buckets.

The core pieces are:

- **[Catalogs](/docs/lakehouse/catalogs.md) define tables**: Altertable catalogs are hosted lakehouse databases for new managed tables. Altertable stores those tables as Parquet files and handles file layout, compaction, caching, and query execution together.
- **[Workers](/docs/lakehouse/workers.md) run SQL**: Workers execute DuckDB SQL, cache hot data locally, and connect Altertable to your sources. Use managed Workers, or deploy them in your own infrastructure.
- **[Buckets](/docs/lakehouse/buckets.md) store files**: Buckets are object storage locations for lakehouse data. Use managed Buckets, or connect an existing bucket so data stays in the account, region, and governance boundary you already operate.
- **[External catalogs](/docs/lakehouse/external-catalogs.md) connect existing data**: External catalogs make databases, warehouses, and file-backed buckets queryable from Altertable without moving them into managed lakehouse storage first.

At runtime, clients send SQL to Workers. Workers read and write Parquet files in object storage, use local SSD for hot data, and can also query external databases and warehouses.

```ascii
                         ╔════════════════ Altertable ════════════════════╗
╔════════════╗           ║                                                ║░
║            ║░          ║   ┏━━━━━━━━━━━━━━━━━━┓    ┏━━━━━━━━━━━━━━━┓    ║░
║   Client   ║░───HTTP──▶║   ┃  Workers         ┃    ┃ Object        ┃    ║░
║            ║░          ║   ┃  ┌──┐ ┌──┐ ┌──┐  ┃    ┃ Storage       ┃    ║░
║            ║░          ║   ┃  │W1│ │W2│ │WN│  ┃───▶┃  ┌─────────┐  ┃    ║░
║            ║░          ║   ┃  └──┘ └──┘ └──┘  ┃    ┃  │ Parquet │  ┃    ║░
║            ║░          ║   ┃                  ┃    ┃  │ File 1  │  ┃    ║░
║            ║░          ║   ┗━━━━━━━━┬━━━━━━━━━┛    ┃  └─────────┘  ┃    ║░
╚════════════╝░          ║            │         ┃    ┃  ┌─────────┐  ┃    ║░
 ░░░░░░░░░░░░            ║    ┏━━━━━━━┻━━━━━━┓  ┃    ┃  │ Parquet │  ┃    ║░
                         ║    ┃   Local SSD  ┃  ┃    ┃  │ File... │  ┃    ║░
                         ║    ┃     Cache    ┃  ┃    ┃  └─────────┘  ┃    ║░
                         ║    ┗━━━━━━━━━━━━━━┛  ┃    ┃  ┌─────────┐  ┃    ║░
                         ║                      ┃    ┃  │ Parquet │  ┃    ║░
                         ║                      ┃    ┃  │ File N  │  ┃    ║░
                         ║                      ┃    ┃  └─────────┘  ┃    ║░
                         ║                      ┃    ┗━━━━━━━━━━━━━━━┛    ║░
                         ║                      ┃                         ║░
                         ╚════════════════════════════════════════════════╝░
                           ░░░░░░░░░░░░░░░░░░░░░┃░░░░░░░░░░░░░░░░░░░░░░░░░
                                                ┃
                                                ┃    ┏━━━━━━━━━━━━━━━┓
                                                ┃    ┃               |░
                                                ┃    ┃    External   |░
                                                ┗───▶┃ DB & Warehouse|░
                                                     ┃               |░
                                                     ┗━━━━━━━━━━━━━━━┛░
                                                      ░░░░░░░░░░░░░░░░
```

## Managed and external catalogs

Use [Altertable catalogs](/docs/lakehouse/catalogs.md) when you are creating new lakehouse tables on Altertable. Use [external catalogs](/docs/lakehouse/external-catalogs.md) to query existing databases, warehouses, and file-backed buckets alongside those managed tables in the same SQL engine.

## Lakehouse sections

- [Catalogs](/docs/lakehouse/catalogs.md): Create hosted, optimized lakehouse catalogs on Altertable, backed by Parquet files in object storage.
- [Workers](/docs/lakehouse/workers.md): Workers are the DuckDB-based compute units that execute queries, cache data, and connect Altertable to your sources.
- [Network](/docs/lakehouse/network.md): How Altertable workers reach your catalogs. Allow these egress IP addresses, or connect through an SSH tunnel when the database is not publicly reachable.
- [Buckets](/docs/lakehouse/buckets.md): Buckets are the object storage units that keep Altertable lakehouse data durable, portable, and scalable.
- [Authentication](/docs/lakehouse/authentication.md): Altertable generates secure credentials for each environment. Access them to connect via the HTTP API, Arrow Flight SQL, or Postgres adapter.
- [SQL engine](/docs/lakehouse/sql-engine.md): Altertable uses DuckDB SQL for all queries, including federated queries across multiple data sources.
- [Performance](/docs/lakehouse/performance.md): Performance characteristics for Workers, cache behavior, and how we benchmark query latency and cost on the Altertable lakehouse.
- [Features](/docs/lakehouse/features.md): Table capabilities for partitioning, time travel, views, search, and incremental processing in Altertable catalogs.
- [External Catalogs](/docs/lakehouse/external-catalogs.md): Connect databases, warehouses, and file-backed buckets to Altertable as external catalogs for federated queries.