Overview
A Data Model is a saved set of relationships between tables in a Datasource, used by Lens to combine columns across tables when authoring Reports. A Datasource can hold multiple Data Models — different relationship sets for different reporting needs — and each is identified by a name within the Datasource.
Data Models are accessed from Data Source → Datasource Management, by selecting a Datasource and clicking its Data Model icon. Models are Datasource-scoped — they cannot reference tables outside the Datasource they belong to. Data Models are authored only on Datasources.
When to use it
- A Report needs columns from two or more related tables in the same Datasource.
- A relationship between tables (foreign key, lookup, parent-child) needs to be reused across multiple Reports.
- An existing model needs to be retired or replaced after a schema change.
Workspace surfaces
| Data Model pop-up | Lists existing Data Models for the chosen Datasource, with per-row Edit and Delete actions and a create new icon. |
| Data Model workspace | Canvas where tables are added as cards and relationships are drawn between columns. Reached by creating a new model or editing an existing one. |
Workspace toolbar
| Save | Persists the current workspace state to the model’s existing name. On a brand-new model, prompts for a Data Model Name on first save. |
| Save As | Persists the current workspace state under a new name, leaving the original model unchanged. Used to fork an existing model. |
| Reset | Clears the workspace back to its starting state. Does not affect the saved model. |
| Refresh | Re-renders the workspace. Used to recover from stale-state issues during long editing sessions. |
| Help | Opens contextual assistance for the Data Model surface. |
Relationship configuration
A relationship is established by drawing a connection line between two columns — one on each of two table cards in the workspace. The columns become the join keys for any query that traverses the relationship. Connection lines are interactive: clicking a line surfaces edit and delete actions, allowing relationships to be reconfigured or removed without rebuilding the model.
Each connection between two columns can be configured with a join type — Inner, Left, Right, or Full outer — that controls how rows are matched across the related tables. In addition to join type, each relationship carries a cardinality that describes the row-count relationship between the two tables — either one-to-many or many-to-one.
Key behaviors
Datasource-scoped. A Data Model belongs to exactly one Datasource and references only tables exposed by that Datasource. To model relationships that span Datasources, create separate models in each and combine results at the Lens Report level.
Multiple models per Datasource. A Datasource can hold any number of Data Models, each named uniquely within the Datasource. Designers select a model when building a Report; switching models can change which tables and relationships are available without modifying the Report’s other configuration. Reports bind to a specific Data Model — if that Data Model is deleted, Reports built on it may break, so confirm no Reports depend on a Data Model before deleting it.
Save As as a versioning pattern. There is no built-in version history on Data Models. Save As is the supported way to preserve a known-good model before making invasive changes — fork first, edit the copy, swap Reports over when validated.
Reset is workspace-local. Reset clears the in-progress workspace state but does not delete a saved model. The saved model is unaffected until Save or Save As is clicked.