> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useautumn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lakehouse Overview

> Query your Autumn data from your own warehouse. v2.6 publishes the objects of Autumn's API as tables.

> [!WARNING]
>
> **Available on request.** The Autumn Lakehouse is provisioned per customer. Contact us at [hey@useautumn.com](mailto:hey@useautumn.com) to get access. Any customer may use our [SQL endpoint](https://docs.useautumn.com/documentation/query-with-sql.md) instead.

The Autumn Lakehouse copies your Autumn data (customers, plans, subscriptions, balances, invoices, usage events) into [Apache Iceberg](https://iceberg.apache.org/) 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`.

> [!TIP]
>
> Coming from v2.3? v2.6 sits beside it in the same namespace, and your v2.3 queries keep working. See [Migrating from v2.3](https://docs.useautumn.com/documentation/lakehouse/v2-6/migrating-from-v2-3.md).

## The tables at a glance

| Table | What one row is | API object |
| - | - | - |
| **Catalog** ([details](https://docs.useautumn.com/documentation/lakehouse/v2-6/schema.md#catalog)) | | |
| `v2_6_features` | A feature you meter or gate, like `messages` | Feature |
| `v2_6_plans` | One version of a plan, with its base price and trial | Plan |
| `v2_6_plan_items` | One feature a plan grants, with its price | `plan.items[]` |
| `v2_6_plan_licenses` | Seats of one plan that another plan includes | `plan.licenses[]` |
| **Customers and plans** ([details](https://docs.useautumn.com/documentation/lakehouse/v2-6/schema.md#customers-and-plans)) | | |
| `v2_6_customers` | A customer | Customer |
| `v2_6_entities` | A user, workspace or project inside a customer | Entity |
| `v2_6_subscriptions` | A recurring plan attached to a customer or entity | `customer.subscriptions[]` |
| `v2_6_purchases` | A one-off plan a customer bought | `customer.purchases[]` |
| `v2_6_customer_plan_items` | An item or price on one customer's custom plan | (rebuilds `subscription.plan`) |
| `v2_6_licenses` | A customer's pool of seats | `customer.licenses[]` |
| **Balances** ([details](https://docs.useautumn.com/documentation/lakehouse/v2-6/schema.md#balances)) | | |
| `v2_6_balances` | One feature's balance, as the customer or one entity sees it | `balances{}` |
| `v2_6_breakdowns` | One grant inside that balance, in the order it's used up | `balance.breakdown[]` |
| `v2_6_rollovers` | Unused balance carried over from an earlier period | `balance.rollovers[]` |
| `v2_6_flags` | An on/off feature the customer or entity has | `flags{}` |
| `v2_6_pooled_balance_contributions` | One plan feeding a shared pool | `breakdown[].contributions` |
| **Invoices, rewards and events** ([details](https://docs.useautumn.com/documentation/lakehouse/v2-6/schema.md#invoices)) | | |
| `v2_6_invoices` | An invoice | Invoice |
| `v2_6_invoice_line_items` | A line on an invoice | `invoice.items[]` |
| `v2_6_coupons` | A discount coupon | Coupon |
| `v2_6_feature_grants` | A reward that grants free balance | Feature grant |
| `v2_6_referral_programs` | A referral program | Referral program |
| `v2_6_referrals` | One use of a customer's referral code | `customer.referrals[]` |
| `events` | A usage event you tracked | Event |

## How the tables connect

```mermaid theme={null}
flowchart LR
  F["features"] --> PI["plan_items"]
  P["plans"] --> PI
  P --> S["subscriptions<br/>purchases"]
  C["customers"] --> S
  C --> E["entities"]
  E -.-> S
  S --> BD["breakdowns"]
  C --> B["balances"]
  B --> BD
  B --> R["rollovers"]
  C --> I["invoices"]
  I --> LI["invoice_line_items"]
```

Every arrow is an `internal_*` id, or `customer_plan_id` and `balance_id`. The [Schema Reference](https://docs.useautumn.com/documentation/lakehouse/v2-6/schema.md) 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](https://docs.useautumn.com/documentation/lakehouse/v2-6/querying.md#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

> [card] [Connecting](https://docs.useautumn.com/documentation/lakehouse/v2-6/connecting.md)
>
> Attach ClickHouse or BigQuery to your catalog.

> [card] [Working with balances](https://docs.useautumn.com/documentation/lakehouse/v2-6/balances.md)
>
> How balance rows work, with a worked example.

> [card] [Querying](https://docs.useautumn.com/documentation/lakehouse/v2-6/querying.md)
>
> Addressing, JSON, and rebuilding a customer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.