Lakehouse Overview

The Autumn Lakehouse copies your Autumn data (customers, plans, subscriptions, balances, invoices, usage events) into Apache Iceberg tables that you query from your own engine, such as ClickHouse or BigQuery. Use it for dashboards, revenue and usage reporting, and joining billing data against your own product data, in SQL, over the full history.

​

What v2.6 is

In v2.6, each table is one object from Autumn’s API, flattened into columns. If you know what POST /v1/customers.get returns, you already know the tables: the customer’s fields are a row in v2_6_customers, each item of its subscriptions array is a row in v2_6_subscriptions, each balance is a row in v2_6_balances, and so on. The numbers match what the API returns, so a balance in the lakehouse is the balance your app sees. Tables are named v2_6_<object> inside the namespace Autumn assigns you, for example <namespace>.v2_6_customers. The usage event log is the one exception: it is not versioned and is called events.

​

The tables at a glance

​

How the tables connect

Every arrow is an internal_* id, or customer_plan_id and balance_id. The Schema Reference lists the exact key of every table.

​

Rules every table follows

• org_id and env come first. env is live or sandbox (never production). Match both in every join.
• Join on internal ids. Each table has an internal key such as internal_customer_id or internal_plan_id, and every reference to another table uses it. Your own ids (customer_id, plan_id, entity_id) are on the rows too, for display and filtering, but they can change or be null, so don’t join on them.
• Plans, not products. v2.6 uses the API’s words throughout: plan_id, internal_plan_id, plan_items. v2.3 called these products.
• Scalar columns only. Every column is a string, boolean, whole number or decimal. Objects and arrays are stored as JSON text, for example event_names = '["message_sent"]'. See Querying → JSON columns.
• Money in major units. Amounts are dollars (or your currency’s main unit), not cents.
• Times in epoch milliseconds. Timestamps are whole numbers of milliseconds since 1970, except events.timestamp, which is a real timestamp.

​

Freshness

v2.6 tables are rebuilt in scheduled runs rather than streamed row by row. A change in Autumn shows up in the tables within about 45 minutes. Each run computes balances at one moment and records it in v2_6_balances.as_of, so you can always tell how current a balance is. The events table is shared with v2.3 and fills in the same way it always has.

​

Versions

The v2_6 prefix is the schema version. A new version arrives as a new set of tables beside the old one, so nothing breaks when it ships, and you move your queries when you choose. v2.3 is now legacy: it stays live until every tenant has moved, and we’ll contact you before it is retired. Use the version menu at the top of the sidebar to read the v2.3 docs.

​

Next steps