A data model is where a business definition is made once. It joins sources — operational entities, archived history, externally landed warehouse tables — into a named structure with declared output columns, and materializes that structure into a physical table in the analytics warehouse. Datasets then build on the model rather than on raw tables, which is the whole point: ten dashboards needing "revenue" means one model defining it, not ten private versions that drift apart.
What a model is made of
A model is authored in the Data Model Builder — an application page (route /analytics/data-models) that an administrator adds to an app's navigation as a Feature item; it is not in Setup. The builder lists models with Name, Label, Root Source, Root Entity, Grain, Warehouse Object, Published (Published or Draft), Active and Updated, with Open Workspace, Edit and Delete per row. New Data Model opens the dialog below.
- 1
Name is the stable technical key; Label on the right is the title dataset authors see.
- 2
Description should state the reusable business definition in plain language.
- 3
Root Source Type — Entity, Warehouse Table or External Warehouse Table — decides whether Root Entity or Root Warehouse Object applies.
- 4
Grain states exactly what one materialized row represents.
- 5
Published Warehouse Object is the physical table every build drops and recreates; a bare name lands in the model schema.
- 6
Published is the offer to dataset authors — there is no separate Publish button. Active (right) decides whether the model participates at all.
The dialog captures the model's contract before any source is joined: Name (the stable key), Label, Description (state the business definition), Root Source Type — Entity, Warehouse Table or External Warehouse Table — with its companion Root Entity or Root Warehouse Object, Grain, Published Warehouse Object, Refresh Schedule (five-field cron, UTC), and the Published and Active checkboxes (a new model is active but unpublished; there is no separate Publish button — publishing is this checkbox). Everything else is authored in the model's workspace, whose tabs are Overview, Sources, Columns, Filters and Build History, with Edit, Build, Validate, Preview and Delete in the header. A model consists of four parts:
- A root source — an operational entity, or a warehouse table (an archive table produced by archive rules, or external data already landed in the warehouse).
- Joined sources — additional entities or warehouse tables, each with an alias, a join type (inner, left, right or full) and a join condition tying it to a parent alias; for an entity source the Relation Helper prefills the entity and join from the parent entity's relations. The join graph must have exactly one root, and every non-root source needs its parent and condition.
- Output columns — the model's published schema: each column maps a source alias and field (or an expression) to an output column name, with a display name, an optional aggregation (Sum, Count, Average, Min, Max, Count Distinct or Expression), a Key Column flag and a Visible flag. These output columns are what datasets see and validate against.
- Filters — predicates ANDed into the build, for scoping the model itself.
The model also carries a grain statement ("one row per sale order"), the warehouse object name its build writes to, a refresh schedule, and two switches that mean different things: Active (the model participates at all) and Published (the model is offered to dataset authors).
What building actually does
Build validates the definition first (a blocking error stops the build and writes no history row), then generates SQL from the sources, columns and filters and loads the result into the model's warehouse object as a physical table — not a view, so downstream reads pay no join cost at query time. Every build is a full drop-and-recreate of that table; a bare object name without a schema lands in the model schema. How the data gets there depends on where the sources live:
- Warehouse sources only — the table is built entirely inside the warehouse from the generated SQL.
- Entity sources only — the qualifying operational data is copied into the warehouse table.
- Mixed — entity data is first staged into the warehouse, the join then runs there against the warehouse-resident sources, and the staging copies are cleaned up afterwards. This is what lets one model combine live records with archived history in a single structure.
Every build appends a Build History entry — started, completed, status (Pending, Running, Succeeded, Failed, Canceled), row count, duration and error message. Builds run on demand from the workspace's Build action (the toast reads Data model build triggered), or on the model's cron schedule; scheduled builds require the model to be active and published, with a valid schedule. The schedule is checked about once a minute, the first occurrence after saving is not back-filled, a malformed cron expression is skipped silently, and model builds send no notification — Build History is the only record, so a model that "never builds" is diagnosed there. Building requires a reachable warehouse; when it is not, the build is refused before anything runs. Validate checks the definition — the join graph, aliases, required columns, expressions — without touching the warehouse, and Preview shows the generated SQL and projected columns before anything runs.
How models relate to datasets
The relationship is a deliberate one-way dependency: datasets consume models, never the reverse.
- Binding. A dataset binds to one published, active model. Binding auto-fills the dataset's source and grain, and is what the dataset's guidance and validation hang off.
- Schema guidance. A bound dataset's editors offer the model's root object and published output columns as pick lists, and its validation rejects references to columns the model does not publish — schema mismatches surface at authoring time instead of as build failures.
- Lifecycle. Rebuild the model and every dataset's next refresh reads the updated structure; unpublish a model and it stops being offered to new datasets. The model is the contract; datasets are its consumers.
A dataset can bypass models and name a warehouse table directly — supported as a fallback, at the cost of all guidance and schema validation. The governed default is: model first, datasets on top.
Common questions
What is the difference between a data model and a dataset?
A data model is a reusable source: the joined, governed structure where the business definition lives. A dataset is a consumption output: dimensions and measures over exactly one model, aggregated to an analysis grain and materialized for dashboards and embedded BI. The test: if several analyses will share it, it belongs in the model; if it is one analysis's shape — which columns to group by, which numbers to aggregate — it belongs in the dataset.
Can a model include archived or external data?
Yes — that is a core reason models exist. A source can be a warehouse table as easily as an entity: archive tables written by archive rules, or external data already landed in the warehouse. A mixed model joins live operational records with that warehouse-resident history in one structure, so "sales including the archived years" is one model rather than a stitching exercise in every report.
What happens if I rename the model's warehouse object after builds?
The next build writes to the new name and the previously built table is simply left behind — orphaned, not migrated or dropped. Anything reading the old name (a dataset's fallback source, BI content built over it) keeps reading the stale table without errors, which is worse than breaking. Treat the warehouse object name as part of the model's contract: set it before the first build and change it only with the downstream consumers in hand.
Why is my model not offered when creating a dataset?
The dataset modal lists models that are both published and active — a draft or deactivated model does not appear, however many successful builds it has. Publishing is the explicit act of offering the model to dataset authors; check both switches on the model's overview before looking anywhere else.