What a semantic model is
A Lens data table holds rows. A semantic model says what those rows mean. It lists the tables that belong to one subject area, such as web analytics or paid media, and defines once:
- the metrics people can ask for, such as Sessions, Spend or Orders, and how each one is calculated,
- the fields people can group and filter by, under the names people actually say,
- the shared fields that mean the same thing in several tables, such as Campaign in GA4 and in Google Ads,
- how each table handles dates and time zones.
Because the definitions live in the model instead of in each tile, one question gets one answer whichever table it lands in. Analyze, Ask Lens and AI connectors answer questions through a model; see Analyze.
You find models under Configure > Models.
Building blocks
| In the model | What it is |
|---|---|
| Dataset | One Lens data table, or one BigQuery table or view, used by the model. Each dataset is either Measured (something you count, like sessions) or a Reference list (something you look things up in, like a store list). |
| What one row represents | The grain of a dataset, for example "one session per day per source". Lens can check that the fields you name really identify one row. |
| Field | A column people can group or filter by, with a display name, a type and a rule for how values are matched. Columns you do not show stay hidden. |
| Metric | A number people can ask for: a count, a sum, an average, a lowest or highest value, or one metric divided by another. |
| Shared field | One field connected to a column in each of several datasets, so any metric can be broken down by it. |
| Segment | A named rule on one field, such as Commercial Pages for page paths that match a pattern. People filter by it by name. |
| Reporting timezone | The zone a period like "last month" is defined in. Each dataset then finds its own rows for that period in its own zone. |
How values are matched
Every shown field has a rule that tells Lens how to read a value someone asks for:
| Rule | Use it for |
|---|---|
| Use its known values | Short fixed lists, such as Device Category. Asking for "phone" finds Mobile. |
| Search current names | Names that change, such as Campaign or Source. When several match, Lens asks which one. |
| Match text in it | Paths and URLs, such as everything under /roofing. |
| Look it up by code | Values stored as a code, such as a state (TX) or a campaign ID. |
| Exact value only | Dates and yes/no fields. |
System packages
A system package brings built-in datasets, fields and metrics for a common source, ready to use once its tables are connected. Packages exist for Echo web analytics, GA4 (Data API and BigQuery export), Adobe Analytics, Google Ads, Meta Ads and Olo. The tables a package expects can be created for you with a recommended data setup.
Anything you change or add after loading a package stays marked as yours. A model built from a package uses Guided setup in the editor; a model built from scratch uses Advanced setup. You can switch between the two on a package-based model.
When a newer package version is published, the model page offers it for review. Nothing changes until you upgrade; see Model Updates.
Status
| Status | Meaning |
|---|---|
| Draft | Being built. It is not offered to anyone asking questions. |
| Active | In use. An active model with no blocking problems answers questions. |
| Archived | Out of the picker, but anything already built on it keeps resolving. Restore it at any time. |
Deleting a model is done from the model list and cannot be undone: anything built on it stops resolving.
Ready or not
Lens checks every model and sorts what it finds into three groups:
| Group | Effect |
|---|---|
| Must fix | The model cannot answer questions until these are fixed. The list shows "N to fix". |
| Worth knowing | Answers will resolve, but some will be limited. The list shows "N to know". |
| Could improve | Optional. |
A model with nothing in the first two groups shows Ready.
Revisions
Every save creates a new revision, and the model page lists them under History. Package upgrades and Terrain decisions also save as new revisions, so an earlier version of the model is always on record.
Default analysis area
One active model per property can be the default analysis area: click the star on its card and confirm. Analyze opens it, and TagPipes AI connectors use it whenever no analysis area is named.
Limits
- Only active models answer questions.
- A BigQuery table or view added to a model is queried in your own Google Cloud project each time a question is asked. Nothing is copied into Lens, and the queries run on your Google Cloud bill.
- Linking a metric or field to a Terrain term is a label. It never changes a query.