Semantic model glossary
The vocabulary of a datahashi model and a datahashi query — entity, dimension, measure, metric, join graph, semantic query, segment, view, and the rest.
Updated
This is the normative vocabulary. The same terms appear in the YAML, the API, and the console — used precisely.
The model
Semantic Model — the layered set of definitions that map physical data to business vocabulary: entities, dimensions, measures, metrics, segments, views, independent of which warehouse dialect backs it. Identified by a name, versioned draft → published. A model binds to exactly one Source.
Entity — a business noun with a primary key and relationships to other
entities, like Customer or Order. Backed by a physical table or by a
curated SELECT.
Dimension — an attribute of an entity used to slice or group results:
region, status, order_date. A time dimension declares the grains it
allows.
Grain — a time bucketing unit applied to a temporal dimension in a query:
day, week, month, quarter, year, hour, minute. At most one grain
per selected time dimension.
Measure — a raw aggregatable field on one entity with a single aggregation:
sum, count, count_distinct, min, max, count_distinct_approx. The
reusable primitive. revenue is sum(amount); order_count is count(id).
There is deliberately no avg.
Metric — a named, governed expression built on one or more measures: a
ratio or arithmetic formula, computed after aggregation. avg_order_value = revenue / order_count. The “one true number,” available to governed
credentials.
Join Graph — the graph of entities connected by named relationships, each with a cardinality and key columns. The compiler traverses it to resolve join paths between the measures and dimensions a query asks for. You never write a join.
The query
Semantic Query — the structured request every consumer emits (REST, MCP, or the console) and the only thing that gets compiled into SQL. Names one model plus some combination of metrics/measures, dimensions (with optional grain), filters, segments, view, order, and a row limit. Never SQL, never a raw table or column name.
Segment — a named, reusable filter fragment defined on the model (“completed orders only”) that a query references by name instead of repeating the same filter everywhere. Expanded before row-level security runs.
View — a named, curated projection of one model’s exposed surface: a subset of its metrics, dimensions, and (in explore mode) measures. Presentation only — it narrows what a consumer may reference, never widens access.
Governed mode / Explore mode — two access surfaces over the same compiler. Governed exposes named metrics and views. Explore also exposes raw measures × dimensions across the join graph. Mode is bound server-side from the credential.
Tenancy and access
Workspace (a.k.a. Org, Tenant) — the isolation boundary that owns sources, models, and credentials. One flat account boundary.
Source — the physical warehouse a model binds to: Snowflake, BigQuery, Postgres, MySQL, DuckDB. A workspace may have several; a model targets exactly one.
Connection — the address plus sealed credential that reaches a source. Rotating a connection re-addresses the same source without renaming it.
Principal — the subject of authorization: a human member or an MCP credential. Policy is evaluated against a principal. Product UI often says “who is asking.”
Data role — a named grant set (entities, fields, metrics, and optional row filters) assigned to members and MCP credentials. Holding several roles unions the catalog and intersects the row filters.
Serving
Rollup (roadmap) — a materialized pre-aggregation: measures pre-aggregated over chosen dimensions at a grain, stored so a hot query path reads an answer instead of recomputing it against the warehouse. Pre-aggregation is on the roadmap, not yet shipped; today every query compiles and runs against the source.