# Modeling overview

> How Flax's dbt-compatible, git-backed semantic model turns raw warehouse tables into governed, reusable metrics

*[View this page in the Flax docs](https://flax-analytics.com/docs/modeling/overview)*

Flax's semantic model is the shared definition of your business: what a "customer" is, how "revenue" is calculated, and how tables relate. You define it once in YAML, and everyone — analysts, viewers, the AI assistant, and the API — explores the same governed metrics. This page is for anyone setting up or maintaining the model.

## Defined once, explored everywhere, governed by review

The semantic layer follows three principles:

- **Defined once.** A dimension or measure is written a single time. Every query, chart, and sheet reuses that definition, so "revenue" means the same thing across the whole organization.
- **Explored everywhere.** The model powers the query builder, dashboards, Sheets, the AI assistant, and the API — all against one source of truth.
- **Governed by review.** The model is **git-backed**. Changes are code changes: reviewed, versioned, and auditable. Edits made in the UI open a pull request rather than silently mutating production (see [Write-back](/docs/modeling/write-back)).

The spec is **dbt-compatible YAML**. If you already have a dbt project, Flax reads your `models/**/*.yml` directly; Flax-specific concepts live under a `flax:` extension key so a file stays a valid dbt schema file.

## What a model contains

A model maps a warehouse table (or dbt model) to a queryable surface with three building blocks:

| Concept | Purpose |
| --- | --- |
| **Dimensions** | Attributes to group and filter by — status, country, order date. |
| **Measures** | Aggregations — `count`, `sum(amount)`, `count_distinct`, and more. |
| **Joins** | Relationships to other models so cross-model queries work. |

```yaml
version: 2

models:
  - name: orders
    description: One row per order placed in the store.
    flax:
      primary_key: order_id
      dimensions:
        - name: status
          type: string
          sql: ${status}
      measures:
        - name: total_revenue
          type: sum
          sql: ${amount}
      joins:
        - name: customers
          type: left
          sql_on: ${orders.customer_id} = ${customers.customer_id}
```

Models can also declare a `primary_key` (for correct counts over fan-out joins) and `access_filters` (row-level security).

## Next steps

- [Dimensions and measures](/docs/modeling/dimensions-and-measures) — define the queryable fields.
- [Relationships and joins](/docs/modeling/relationships-and-joins) — connect models together.
- [Semantic YAML reference](/docs/modeling/semantic-yaml-reference) — every field Flax supports.
- [SQL compilation](/docs/modeling/sql-compilation) — how the model becomes warehouse SQL.
- [Row-access filters](/docs/modeling/row-access-filters) — restrict which rows a user can see.
- [Lineage](/docs/modeling/lineage) and [Write-back](/docs/modeling/write-back).