For stewards

Editing the semantic model

Metrics, dimensions and segments as YAML, and which side wins.

The semantic model sets out what your metrics, dimensions and segments are: how net revenue is calculated, what you can slice it by, and which rows count as completed. Ask builds a query from this model when you ask for a number. This page shows how to edit it as YAML, and what happens when the YAML and an asset page disagree.

Before you start

Anyone can read the Semantic model screen. To save it you need Edit the semantic layer (SEMANTIC_EDIT). In the starter model it comes with Sysadmin and Metadata Manager.
Changing what a metric means can change every number built on it. Use the preview every time.

What is on the screen

Open Semantic model in the sidebar, under Administration. You'll see:

the whole model as YAML, in the Cube format: models (cubes) with their dimensions, measures, joins and segments
a notice, Asset-level changes take more weight., which explains the rule below
any fields currently held by the asset pages, listed before you type anything
a line saying who last saved it, when, and their note

Each metric, dimension, segment and model is also an asset in the repository with its own page. The YAML and those pages are two views of the same model.

Preview a change

Edit the YAML in the box. Indent with spaces; a tab is turned into spaces as you type.
Press What would this do.
Read the preview. It lists what would be added, changed and removed. If something would stop the save, it says This will not run. and gives the reasons. If nothing would change, it says so.

If the text isn't valid YAML, or isn't a model, you'll see Not a model. with the reason. Nothing is written by a preview.

Save it

Optionally, type a note in What changed, and why (optional).
Press Save.

KRISID works out the preview again and, if nothing blocks it, applies it. You'll see a summary such as Saved. 1 added, 2 changed, 0 removed, 1 left alone. If anything blocks the save, the whole save is refused and nothing is written.

To throw away what you've typed, press Revert to what is stored.

One thing is always refused: removing a metric that another metric is calculated from. The message names the metric that would be left without a definition.

Which side wins

A value edited on an asset's own page wins over the YAML, such as a description, a classification or a grain. Pasting a file doesn't overwrite it.

The YAML is where the model is authored. The asset page is where a steward refines it, and the steward's word is kept. It's the same idea as a harvest, where a source's comment never overwrites a steward's description.

So when you preview or save, KRISID first names every field it is leaving alone:

a count, such as 1 field will not be taken from this YAML.
one line per field, marked kept, naming the model and metric (for example orders.net_revenue), the field, who edited it on the asset page and when, and what the YAML says instead

Everything else in the file is applied as normal. Nothing is skipped or overwritten without being listed.

Clearing a field on an asset page on purpose counts as an edit too. The YAML won't put the old value back.

Let the YAML win for one field

If the YAML's value is the one you want:

Find the field in the list of kept fields, either at the top of the screen or in the preview.
Press Let the YAML win beside it.
Confirm with Let it win, or press Keep to change your mind.

The field is released. What was written on the asset page is lost, and the next save takes the YAML's value. You'll see a message naming the field that now takes its value from the YAML. This also needs Edit the semantic layer.

To change the value going forward, you can instead edit it on the asset page. It stays held there.

Good to know

The YAML round-trips: saving the file you were shown, unchanged, changes nothing. That's what keeps it usable in version control or in Cube later.
Ask composes queries from this model but never runs them. See Metrics and asking for a number.
A business term can be linked to the metric that calculates it (realised by), so the term's agreed meaning and the metric's calculation stay together. See The business layer.