A semantic model binds one table and names the vocabulary you can compute from it. Create one from Semantic layer with New model, or from an object’s page in Explore using “Define a model on this object”, which pre-fills the binding for you. Creating a model is a full page, not a dialog — the same form editing uses — because a model grows without limit (dimensions, measures, relationships and metrics) and a half-finished document needs a place to live while you work on it. Saving always creates a draft; nothing is proposed or certified from this page. A model can also be authored outside the console, from a document — dip semantic create takes a full model definition and dip semantic import an OSI document, each landing a draft, and dip semantic propose submits it for review. Certifying still happens here, by a person; the CLI drafts and proposes but does not bless. On the model list, Metrics is the total number of queryable numbers owned by each model: its measures plus its composed metrics. Open a model to see the same numbers with their definitions.

Binding a dataset

A model binds exactly one catalog, schema and table. Pick them with the cascading Bound dataset picker: choosing a catalog loads its schemas, and choosing a schema loads its tables, all read from the crawled catalog index — so browsing here starts no engine. If a level has not been crawled yet (or the index cannot be read), that part falls back to a plain text box you type into, and each level offers a “Not listed? Type it” escape for an object the crawl has not caught. The three parts are always kept separate — never a dotted catalog.schema.table string — because a table name may legitimately contain a dot. If the same business idea (say, “Customer”) lives in more than one table, model each table separately and connect them later with a concept — a model itself cannot span more than one dataset.

Dimensions

A dimension is an attribute to slice by — a region, a channel, a date. Every group-by and filter in a metric query names one. In the console, Column type fills itself in when the expression is a bare column of the bound table and the catalog has indexed that table. Type an expression such as order_id and the field shows the column’s type, for example bigint, with the note “From the catalog index.” You can change it, and a type you type yourself is never replaced. An expression that is not a single column, such as lower(region), stays blank, because its type is not any one column’s. So does a column whose type Dippr cannot store as a column type, such as a long nested row(...). When you open an existing model, a dimension with no column type is not changed for you: if the catalog knows its column’s type, a Use button under the field offers it, and one click sets it. The Grain, a measure’s Aggregates over, and the model’s Default aggregation time are all disabled until at least one dimension is ticked Time — they have nothing to point at otherwise, and each shows a short “tick Time to enable” hint while disabled. The first time you mark a single time dimension, it is selected as the model’s default aggregation time automatically (the common case where there is only one clock); a model with two timestamps still asks you to choose.

Measures

A measure is a raw aggregation over the bound table, such as sum(amount) or count(*) — the building block every metric starts from. You can query a measure directly, the same as a metric. Every measure with a compilable aggregation (anything except expression, covered in the warning below) needs a time dimension to aggregate over: its own, or the model’s Default aggregation time. Such a measure with neither is refused when the model is saved, created or imported, with a message naming the model and the measure. The editor marks the measure row before you save. A model already saved with such a measure also stops draft metrics from compiling for everyone who can see it, until the measure is fixed or removed. A table with no date column (a product list, a region lookup) is a dimension table: give it dimensions and no measures, and let the models that join to it do the aggregating. A model with dimensions but no measures is valid; it answers no metric of its own and gives its dimensions to every model that references it.
The expression aggregation is stored and exported, but this platform cannot compile it. A model using it is refused when you try to propose it, and the measure is marked “not compilable” on the model page until it is changed to a supported aggregation.
Some measures need more than an aggregation to mean what they say:
  • Percentile requires a percentile between 0 and 1 (0.5 is the median), and always uses the approximate calculation — an exact percentile is not supported.
  • Semi-additive measures (a balance that can be summed across accounts but not across time) need a non-additive time dimension declared explicitly. Getting this wrong does not raise an error — it silently multiplies the balance by the number of days in the range — which is why it has to be stated rather than inferred.

Relationships

A relationship names another model this one’s rows point at — an order naming its customer — which lets a metric here be grouped and filtered by that model’s dimensions. Joins are implicit: two models join because they share a named business idea, not because you draw a join clause. Only many-to-one and one-to-one relationships are supported. A metric that would need more than two hops of joins is refused rather than approximated.

Metrics

A metric is a named business number built from measures and other metrics. Where a measure says how a column rolls up, a metric says what the number means, and it is what people and agents actually ask for by name. A metric can also carry its own filters, on top of any filters on the measures or metrics it draws from. Filters combine with AND by default; grouping filters lets you express an OR. Filter dimensions use the model-qualified name shown in the Dimensions table. For example, filter an order metric by status with orders.status, not status. This applies to filters on the metric, its measure, and its metric inputs. The service rejects a bare or undeclared dimension when you save the model, before any warehouse query runs.

Filter values and column types

A filter value is written in SQL according to its dimension’s Column type. The same value 1 is a number on a bigint dimension and text on a varchar one, and Trino refuses to compare a number column with text. So Dippr checks every filter value against the column type before a model can be reviewed. What happens when a value does not fit:
  • Proposing a model is refused if one of its metrics filters by value on a dimension with no column type. The message names the model, the metric, the dimension and the value, and says to set the dimension’s column type and propose again.
  • Proposing is also refused when a value does not fit the declared type, for example abc on a bigint dimension or 2026-02-30 on a date one. The message names the dimension and the value.
  • Certifying is refused for a version that was proposed before these checks existed and fails them. Set the column type and propose the model again.
  • A timestamp with time zone value needs its zone, written UTC, Z or an offset such as +05:30. Without one, the same filter would select different rows depending on the session’s time zone, so it is refused.
  • Types a filter value cannot be written for, such as json, array(...) or time, refuse every filter with a value. A like filter works on text dimensions only.
  • Filters with no value (is null, is not null) work on every dimension, typed or not.
Metrics certified before a dimension had a column type keep answering exactly as they did. The check applies the next time the model is proposed. Query filters, the ones you add when you ask a question, follow the same rules: on a typed dimension the value is sent as a number, a boolean or text to match the column, and a value that does not fit is refused before the query runs. A query cannot filter a date or timestamp dimension by value; use the query’s time range, or put the filter in a metric definition. On a dimension with no column type, a query filter value is sent as text.

Time spines

Cumulative metrics and custom time grains (a fiscal quarter instead of a calendar one) both need a time spine — a date table with one row per period. Declare it from a settings card on the Models tab of Semantic layer itself, not under Settings — a time spine is what makes these two features possible at all, so it lives with the models it applies to. Without one, those two features cannot be defined at all. Time spines are shared across every model, because a cumulative metric on one model and a custom grain on another need to agree about what “a month” means. Derived metrics with offset inputs, such as week-over-week revenue, also need a time spine at day grain or finer. A weekly or monthly spine is too coarse. Add a compatible spine in the Models tab before proposing the model; validation refuses an offset metric without one. The query must also group by metric time or the applicable aggregation-time dimension. A draft whose time dimension uses a custom grain that no time spine declares is refused when proposed, and until it is fixed it is left out of every draft preview, together with any draft whose metrics use it. Previewing other models’ draft metrics works as usual; previewing one of its metrics, or grouping by one of its dimensions, is refused with a message naming the model, the dimension and the grain.

Certification: draft, proposed, certified, deprecated

A new model always starts as a draft. Nothing you define is visible to anyone compiling metrics until it is proposed and certified.
1

Propose

Snapshots the current draft as an immutable version and sends it for review. Proposing re-validates every expression, so a definition that cannot compile never reaches a reviewer.
2

Certify

Names an exact version to bless. From that moment, every consumer — the console, the API, and every agent through MCP tools — computes this model’s metrics from that version.
3

Deprecate

Retires a certified model. It stops being served, but its definition and history remain. Deprecation is permanent — a deprecated model can never be proposed, certified or brought back to draft again. To bring the metric back, someone builds a new model and takes it through review from scratch, which forces a fresh look rather than reviving a definition nobody re-examined.
A few behaviours worth knowing before you certify or edit a live model:
  • A certified model under re-review keeps answering. If you propose a new version of an already-certified model, its status becomes “Proposed” while consumers keep getting the previous certified version until the new one is certified. Status describes review state, not availability.
  • Editing a proposed model withdraws it. There is no separate reject action — saving an edit to a model that is under review withdraws the proposal, and this is recorded like any other transition. Where it lands depends on whether the model has ever been certified: a first-time proposal goes back to draft, but a proposal that was re-reviewing an already-certified model goes back to certified — it still owes its consumers the version they were promised, so status reverts to what’s actually being served while your edit sits as the new, uncertified head.
  • Certifying always names the version you saw. If the model changed underneath you between opening the review and clicking Certify, the certification is refused rather than silently applied to a version nobody reviewed.
  • Re-certifying a version that’s already served does nothing new. The option only appears when there is a newer version to bless.

Previewing and running a metric

Open a metric’s “Ask this” panel to build a query against it: pick group-bys, filters and a time range, then choose which query engine to run it on. The panel compiles your question centrally into SQL and runs that SQL on the engine you chose, under your own access — so a table you cannot see behaves exactly as it would on any other query, including a masked column or a denied table. When you preview a draft, an invalid filter in an unrelated draft does not block your query. The preview leaves that draft out and returns a warning naming it. If your query depends on the broken model, compilation stops with model "<name>" cannot be compiled and the reason. Fix the named model before retrying. This also applies to dip semantic preview.
If the engine you pick has scaled to zero, running the query starts it first, the same as running any other query against a cold engine.
The result grid under the form reflects how you asked the question:
  • Formatted values. Each measure’s format hint is applied to its column, so a revenue double reads as $22,962,470.40 rather than 22962470.39999999. Exact decimal columns are shown verbatim to preserve their precision, and columns without a hint are unchanged.
  • Sorted the way the query asked. The grid opens in the query’s own Order by. Click any column header to re-sort it in the browser (click again to flip direction); this only reorders the rows already fetched and never re-runs the query.
  • A chart view. For a numeric result, a Table / Chart toggle draws a simple bar chart — bars are labelled by the first text column (or the row number), and when a result has more than one numeric column you pick which to plot.
If your tenant has not configured a compile service, definitions still save, propose and certify normally — you just cannot ask a metric from the console until a compile service is configured.

Save a good example as a verified query

Once a metric query answers a real question well, save it as a verified query from the Ask panel. See Questions and review for how these move from proposed to verified.

Editing restrictions

A model’s editable head can always be changed by anyone with edit access, regardless of the model’s status — editing a draft, a certified model, or even a deprecated one all land as an edit to the head. What differs is the consequence:
  • Editing a draft changes nothing anyone else can see yet.
  • Editing a proposed model withdraws the proposal (see above).
  • Editing a certified model does not touch what is currently served — you are working ahead, and nothing changes for consumers until you propose and certify the new head.
  • Editing a deprecated model changes its saved definition, but its status stays deprecated: deprecation is permanent, and there is no transition back to draft, proposed or certified. A retired metric can’t be revived — build a new model and take it through review from scratch instead.
A model can have individual metrics or measures hidden from you even when you can see the model itself. Editing replaces the whole document, so saving the model you were shown would delete those hidden definitions. The service refuses to save whenever any metric or measure is withheld from your view, rather than silently dropping what you couldn’t see — the same protection the concept editor has. If you hit this, ask an administrator for access to the withheld metrics first.
Deleting a model removes its version history and certification events along with it — this is your tenant erasing its own vocabulary, not an audit action, so there is no way to recover a deleted model’s history afterward.

Semantic layer overview

What models, metrics and concepts mean, and how they move from draft to certified.

Questions and review

Where a saved query moves from draft to a verified answer your tenant stands behind.