A semantic model joins Kater datasets, and other semantic models, into one place to analyze. In the Shared models editor you select a base, add the sources that join to it, tick the fields people need and check each join on your warehouse. Most workspaces and Explore start from one.

Under the editor, a semantic model is a SELECT that keeps the fields it projects, joins its sources with RELATIONSHIP, and can add dimensions, measures and required filters. Everything you do in the editor writes that SQL.

When to use one

• Your question spans tables. Orders with their customers, or sessions with their paid media.
• You want a curated surface. Pass through only the fields people need, with descriptions and business questions, so agents select from one model.
• You need a measure over several datasets. Declare it here, once.

A semantic model is optional. If one Kater dataset answers the questions, a workspace can read it directly.

Example

1
---
2
name: shop
3
model_type: semantic
4
label: Shop
5
---
6

7
SELECT
8
  o.order_id,
9
  o.region,
10
  o.currency,
11
  o.order_date,
12
  ...
13
  c.country,
14
  c."loyalty tier",
15
  o.sum__amount,
16
  o.count_distinct__order_id,
17
  c.count_distinct__customer_id,
18
  DIMENSION(
19
    'region_group',
20
    KATER__MAP(o.region, ('EMEA', 'Europe'), ('AMER', 'Americas'), default_label => 'Rest of World')
21
  ) AS "Region Group",
22
  DIMENSION('amount_band', KATER__BUCKET(o.amount, [25, 100])) AS "Amount Band"
23
FROM kater_dataset.orders AS o
24
-- @label Customer
25
LEFT JOIN RELATIONSHIP('customer', kater_dataset.customers AS c ON o.customer_id = c.customer_id, 'many_to_one')
26
WHERE
27
  REQUIRED_FILTER('is_not_null__order_id', KATER__IS_NOT_NULL(o.order_id), label='Order ID is set')

• Bare fields pass through. o.region keeps the dataset’s field, and o.sum__amount stays the dataset’s Revenue measure, now with this model’s join and filter around it. Ticking a field in the editor writes a line like these.
• New fields are declared. region_group and amount_band belong to this model. The Derive menu writes calls like these, and the editor marks them Made here.
• The join is a relationship. Each order has one customer, so it is many_to_one. If no field of c is used, Kater leaves the join out. The joins diagram draws it as a line from orders to customers.
• The required filter always applies. Every reader sees only orders with an order ID. Details lists it under Always filtered.

Keys and calls

Rules

• It exposes only what it projects. A field you leave out of the SELECT is not in the model. In the editor, it is unticked, under Not in the model.
• Declare a new field only when the definition changes. Give it a new name. MEASURE('revenue', EVAL(s.revenue)) fails, because revenue is already in scope.
• No parameters or optional filters. Readers narrow the data in their workspace. A shared model holds only filters with fixed values.
• A window here is a dimension. Such as each session’s step number. CUSTOM_CALCULATION is not allowed.
• Joins sit on the root SELECT. Not inside CTEs, subqueries or union branches.
• Its GROUP BY, ORDER BY and LIMIT shape only its own run. A reader re-totals each measure from the source rows at the reader’s own grouping.

Make one

When your agent builds it

Your agent writes through the same operations, and you can watch the model fill in. Each source and join it adds is marked New until you open it. The History tab lists each of its changes, with Show change and Undo. A toast says what it made, such as “Claude Code made Client Engagement: 3 sources, 2 joins, 26 fields.”

The editor

Open a model from the Model Selector, from Files, or by its address. The editor has one sidebar, a toolbar, the joins, the grid and a footer.

Everything saves itself. A tick, a join change or a label shows at once, and the footer says Saving 2 changes, then Saved. Edit › Undo takes back each change exactly.

Rows and Fields

• Rows shows the model’s sample at its grain, 200 rows at a time, with the total, such as 200 of 18,603 rows. A model you have not edited reads its kept sample, so opening it never runs it again. The menu at the right sets which fields show, such as 13 of 60 fields shown.
• Fields lists one row per field, to edit like a spreadsheet. See The Fields sheet.

The side panel

Select a join, a source or a field, and its panel opens at the right. The joins and the grid narrow to make room.

• A join. Its sources, keys, how rows match, the warehouse check, rows kept, measures and its description. See Relationships and joins.
• A source. Its address, Alias, how many of its fields are in the model and how many more you can add, the join that joins it, and its description and tags. Then Preview sample, an item that opens the source in the editor in a new tab, such as Open GA4 Client Lifecycle in the editor, Replace with another source, Show in SQL, Show in Files and Remove source.
• A field. Where it comes from, whether it is in the model, its label, name, formula, description, AI context, format, values, tags and business questions. See The field panel.
• Details. The model’s own label, description and more. See below.

Keyboard

Model details

Select Details on the toolbar. The panel holds the model’s frontmatter: Label, Description, AI context, Business questions, Tags and Always filtered, each list with Add. Show as YAML shows the frontmatter as the file has it. See Formats, descriptions and AI context.

Definitions and Explore

The header switches views. Definitions shows a card per field, by Measures and Dimensions made here: its address, its description and what it computes, with On this page at the right. Explore shows the starting analyses Explore offers for the model. View › Lineage, or More › Show lineage, traces each field to the columns it reads.

Explore’s settings for a model live beside it, in explore/semantic/<name>.explore.yaml in the model’s folder. See Explore.

History

Select the History tab, or Edited 2 min ago in the header. History lists every change to the model’s file, by day: who made it and with which agent, a summary, Show change for its diff, and Undo. Older changes shows more.

The SQL pane

Select View › SQL editor, or SQL in the footer. The SQL pane opens above the joins, with the file’s path and its problems.

• The selected join is lit. Select a join, and its lines light up in the SQL. Click in a RELATIONSHIP, and that join is selected.
• Typing redraws the editor. After a pause, the joins and the field list redraw from what you typed. They keep the last drawing until the new one is ready.
• The usual help. Completions, hover and go to definition work as they do in Files and VS Code.

Menus

The Model menu holds what you do to the whole model.

• File. New semantic model, New Kater dataset and New. Duplicate, and Start a workspace from this model. Show in Files, Open in VS Code, and Open in Sandbox. Share, Copy link and Pin to Home. All shared models.
• Edit. Undo and Redo. Copy, and Copy rows as CSV. Add source, Add field, and Add a filter that always applies. Find in rows and Search fields.
• View. Editor, Definitions and Explore. The sidebar’s Fields, History and Tests, and Hide sidebar. SQL editor, Joins, Rows, Fields sheet, Details, Lineage, Compiled SQL and Problems. Theme.
• Help. Documentation, Modeling guide and Keyboard shortcuts.

Links open the same view

The page’s address holds what you see, so a reload or a shared link opens the same view, and an agent can read where you are. In Files, a model file keeps the same keys beside Files’ own.

From a terminal

kater new semantic-model --name NAME --target-path PATH --sql-file BODY.sql --dry-run shows the file it would write. Run it again without --dry-run to write it. The Model a new table starter walks your agent through the same work.

Common errors