Introduction to Altertable Lakehouse

At the heart of Altertable is a set of hosted DuckDB workers that run your queries inside preconfigured SQL sessions.

                         ╔════════════════ Altertable ════════════════════╗
╔════════════╗           ║                                                ║░
║            ║░          ║   ┏━━━━━━━━━━━━━━━━━━┓    ┏━━━━━━━━━━━━━━━┓    ║░
║   Client   ║░───REST──▶║   ┃  DuckDB Workers  ┃    ┃ Distributed   ┃    ║░
║            ║░          ║   ┃  ┌──┐ ┌──┐ ┌──┐  ┃    ┃ Storage (R2)  ┃    ║░
║            ║░──Arrow──▶║   ┃  │W1│ │W2│ │WN│  ┃───▶┃  ┌─────────┐  ┃    ║░
║            ║░  Flight  ║   ┃  └──┘ └──┘ └──┘  ┃    ┃  │ Parquet │  ┃    ║░
║            ║░          ║   ┃                  ┃    ┃  │ File 1  │  ┃    ║░
║            ║░───PG───▶ ║   ┗━━━━━━━━┬━━━━━━━━━┛    ┃  └─────────┘  ┃    ║░
╚════════════╝░ Adapter  ║            │         ┃    ┃  ┌─────────┐  ┃    ║░
 ░░░░░░░░░░░░            ║    ┏━━━━━━━┻━━━━━━┓  ┃    ┃  │ Parquet │  ┃    ║░
                         ║    ┃   Local SSD  ┃  ┃    ┃  │ File... │  ┃    ║░
                         ║    ┃     Cache    ┃  ┃    ┃  └─────────┘  ┃    ║░
                         ║    ┗━━━━━━━━━━━━━━┛  ┃    ┃  ┌─────────┐  ┃    ║░
                         ║                      ┃    ┃  │ Parquet │  ┃    ║░
                         ║                      ┃    ┃  │ File N  │  ┃    ║░
                         ║                      ┃    ┃  └─────────┘  ┃    ║░
                         ║                      ┃    ┗━━━━━━━━━━━━━━━┛    ║░
                         ║                      ┃                         ║░
                         ╚════════════════════════════════════════════════╝░
                           ░░░░░░░░░░░░░░░░░░░░░┃░░░░░░░░░░░░░░░░░░░░░░░░░
                                                ┃
                                                ┃    ┏━━━━━━━━━━━━━━━┓
                                                ┃    ┃               |░
                                                ┃    ┃    External   |░
                                                ┗───▶┃ DB & Warehouse|░
                                                     ┃               |░
                                                     ┗━━━━━━━━━━━━━━━┛░
                                                      ░░░░░░░░░░░░░░░░

Learn the fundamentals: Read about Insights, Agents, and Architecture to understand how the analytical database fits into the platform.

The lakehouse encompasses all data catalogs in your environment. There are two kinds of catalogs:

Altertable catalogs: managed data stores you create in Altertable and back with a selected bucket.
External catalogs: your existing databases and warehouses connected to Altertable for federated queries.

If you enable Product Analytics for an environment, Altertable also provisions a read-only managed catalog named product_analytics. Altertable writes product events, identities, and derived web analytics tables into that catalog automatically.

Buckets provide the storage layer for managed catalogs and bucket-backed external catalogs such as Bucket Tables and Iceberg Tables. Every environment includes a built-in bucket, and you can connect additional buckets from Cloudflare R2, Amazon S3, Google Cloud Storage, or S3-compatible providers when you need to control where files live.

You may create as many catalogs as you want, for instance:

product_analytics ( built-in product analytics catalog (enabled per environment) )
Table	Description
`main.events`	Raw events (everything `/track` receives)
`main.identities`	Raw identities (everything `/identify` receives)
`analytics.events`	Identity-resolved events for behavioral analysis
`analytics.identities`	Alias and anonymous-resolved identities
`analytics.web_sessions`	Aggregated session data
`analytics.web_pageviews`	Page-level analytics
acme_lakehouse ( your Altertable catalog )
Table	Description
`main.users`	Example of raw table copied by your ETL
`main.orders`	Example of raw table copied by your ETL
`main.products`	Example of raw table copied by your ETL
`main.subscriptions`	Example of raw table copied by your ETL
`analytics.users`	Example of analytics table generated by DBT
`analytics.journey`	Example of analytics table generated by DBT
`analytics.features`	Example of analytics table generated by DBT
`analytics.retention`	Example of analytics table generated by DBT
acme_pg ( external catalog (Postgres) ) Production database read replica
Table	Description
`public.users`	User accounts and profiles
`public.orders`	Customer orders
`public.products`	Product catalog
`public.subscriptions`	Customer subscriptions