Create a Semantic Model

Before you start

• The data the model reads must already exist: Lens data tables, or a table or view in your own BigQuery project. For GA4, Adobe, Google Ads, Meta Ads, Olo or Echo, a recommended data setup creates the tables a package expects.
• To read BigQuery directly, add a Google service account under Security & Access. It needs BigQuery Job User on the project and BigQuery Data Viewer on the dataset.

Read Semantic Models first if the terms are new.

Start a model

1. Go to Configure > Models and click + New Model (or + Create Your First Semantic Model on an empty list).
2. On 1. Basics, enter a Name (for example "Web Analytics"; short and recognizable beats precise) and, optionally, What is this model for?
3. Leave Status on Draft while you build. Only an Active model with no blocking problems answers questions.
4. Optional: under System Package, pick a package and a Version, then click Use this package. Its datasets, fields and metrics load into the draft with no table connected yet. Loading a package into a draft that already has content asks before replacing it.

A model with a package opens in Guided setup, with four steps: 1. Data, 2. Definitions, 3. Reporting and 4. Review & Test. Click Advanced setup at the top for the full editor, described below. Both edit the same draft.

Step 1: Add the data

On 2. Data, under Add a dataset from:

• TagPipes data table: tick the Lens tables that belong to this model.
• BigQuery table or view: connects a table, view or table family in your own Google Cloud project (see below).

For each dataset, answer the questions on its card:

Add a BigQuery table or view

Click BigQuery table or view to open Add Dataset From BigQuery. Lens reads the data in place each time a question is asked; nothing is copied.

1. Pick the Connection, then the Project and Dataset it can see.
2. Pick the Table, view or table family. A table family is a set of daily tables, like transactions_20260901, transactions_20260902, read as one dataset.
3. Pick the Date field. Every question is limited to a date range on this field, which keeps BigQuery costs down. Set Timezone of the dates when the dates are local.
4. Optional: pick an Event time (and the unit it is counted in) when rows carry a precise timestamp, and add Parameters to read one value per row from a key/value list, such as the page_location entry of event_params.
5. Optional: change the Name in this model.
6. Click Check and Add. Lens checks the connection, permissions and fields with a free BigQuery dry run before adding the dataset.

Step 2: Choose the fields

On 3. Fields, every column Lens found is listed. Show the ones people ask about, give each the name people actually say, and leave the rest hidden. Use the Shown, Hidden, Suggested and Shared chips to filter, select several rows to Show these, Hide these or Mark as shared..., and click Add From Columns to pick columns in bulk.

For each shown field, set how values are matched. Lens suggests a rule from the column name; see Semantic Models.

Under Segments, click Add Segment to name a rule on one field, or Add From Terrain to copy the latest agreed version of a Terrain term's filter rules. A later change in Terrain never changes the segment by itself.

Step 3: Define the metrics

On 4. Metrics, click Add From Columns, Add Metric or Add Calculated Metric. Click any metric to open its full definition. A metric is one of:

Step 4: Connect shared fields

On 5. Shared, click Add Shared Field and connect one column per dataset, for example GA4 campaign and Google Ads campaign_name as Campaign. Any metric can then be broken down by it, whichever dataset the metric lives in. Find Matches Automatically suggests pairs; Review All Wording lists every word the model will recognize.

Step 5: Set the time rules

On 6. Time, pick the model's Reporting timezone, then set the zone each dataset is stored in and the periods it can honestly answer. A period like last month is defined once, in the reporting timezone, and each dataset finds its own rows for it.

Step 6: Check and try it

1. On 7. Check, click Check Again. It checks what is on screen, including edits you have not saved, and lists what must be fixed, what is worth knowing and what could improve.
2. On 8. Try It, use Pick a metric (a Measure, Broken down by and a Period, then Run), or Ask in words to type a question the way people in your organization say it.
3. Click Save Model. Every save is a new revision.
4. When nothing is left to fix, set Status to Active and save again.

Check it worked

Open the model from the list. The page header says Ready, It works, but some answers will be limited, or Not ready to answer questions with a Fix it button. The same page has Try It with both modes, so you can prove a saved model answers before anyone relies on it. An active, ready model shows an Analyze button.

A Try It result is one of:

Troubleshooting