The Data Brief · Issue #4 · Semantic Layer Series

Define it once. Mean it everywhere.

How to design a semantic model your whole organization actually agrees on

Shrikant·April 15, 2026·8 min read

61%

Of organizations use four or more BI platforms — Forrester 2025

300%

Increase in LLM accuracy when querying a semantic layer vs. raw tables — Kaelio 2026

10s

If a metric definition takes more than 10 seconds to understand, it's not ready — ThoughtSpot

Most semantic layer projects fail before a single line of YAML is written. Not because of the tooling. Not because of the infrastructure. Because the organization never agreed on what "revenue" means.

The technical implementation of a semantic model is, frankly, the easier part. The harder part is the conversation you have to have with Finance, Sales, Marketing, and Product before you open your IDE. Get that conversation right and the model almost writes itself. Skip it and you will spend the next twelve months maintaining five versions of the same metric, each subtly wrong in a different way.

Start before the model: the discovery conversation

Before modeling anything, you need to understand how your organization actually uses data today — not how it thinks it does. Interview the people closest to the metrics: Finance, Ops, Product, Marketing leads. Not the data team. Business leads know what the numbers are supposed to mean.

The discovery checklist. For each candidate metric: What is the business question this metric answers? Who owns the definition? What are the edge cases (refunds, trials, internal accounts, multi-currency)? Are there known variants already in production? Which source systems feed it — and do they agree?

Pick the handful of KPIs that show up in every leadership meeting — customer count, revenue, CAC, retention — and define those first. These become your anchor metrics.

The four building blocks of every semantic model

1. Entities

The core business objects your organisation reasons about: Customer, Order, Product, Account, Campaign. They map to physical tables but carry business meaning — defining what a "row" represents in human terms, including whether trials count and how duplicates are resolved.

2. Dimensions

The attributes you use to slice and filter metrics — Region, Product Category, Customer Segment, Time Period. The key design decision is granularity: a Region dimension that works for a US-only business will break the moment you expand internationally unless you planned for country, state, and territory hierarchies upfront.

3. Measures

The raw aggregatable values that metrics are built from — SUM(order_amount), COUNT(DISTINCT customer_id), AVG(session_duration). Measures live close to the data and must be expressed using aggregate functions. A good measure definition is specific enough to be unambiguous but general enough to support multiple derived metrics.

4. Metrics

Named, governed business calculations built on top of measures. Revenue, Customer Acquisition Cost, Monthly Active Users, Net Revenue Retention. A metric is not just a formula. It is a formula plus a business decision about what to include, what to exclude, and which edge cases to handle.

The metric definition trap. SUM(order_amount) is a measure. "Revenue" is a metric — and revenue means: gross or net? Does it include tax? Does it include refunds? Does it exclude internal test orders? Does it use booking date or recognition date? Each of those is a business decision, not a technical one.

Naming conventions that prevent future drift

Use snake_case consistently, everywhere

monthly_active_users, not MonthlyActiveUsers or MAU. Abbreviations are a major source of drift — spell it out.

Encode the aggregation type in the name

Prefix or suffix metrics with their aggregation: revenue_total, sessions_count, load_time_avg_ms. This prevents applying a second SUM on top of an already-aggregated metric.

Name for the business question, not the calculation

customer_acquisition_cost tells you what it is. The formula will change; the business question won't. Business names age better than formula names.

Every metric needs a plain-language description

If someone can't understand a metric definition in under 10 seconds, it is not ready. Write the description as if explaining to a new Finance analyst: what does it measure, what does it exclude, who owns the definition.

Synonyms are a first-class citizen

Modern tools including Snowflake Semantic Views and Databricks Metric Views support synonym definitions. When an AI assistant or business user asks for "MRR" or "monthly recurring revenue," they resolve to the same governed definition.

Time intelligence: the dimension nobody designs properly

Time is the most universal dimension and the one most frequently under-designed. Most teams add a date dimension and consider it done. Then someone asks for "revenue this fiscal quarter" and the model has no concept of a fiscal calendar.

Time intelligence checklist before you build. Does your organization use fiscal or calendar quarters? Which time zones matter — user-local, server, or UTC? Do you need rolling windows (7-day, 28-day, 90-day)? Do you need period-over-period comparisons (WoW, MoM, YoY)? Do you need "as of" reporting for point-in-time analysis? Each yes adds design requirements.

What a well-designed metric definition actually looks like

models/metrics/revenue_metrics.yml (dbt MetricFlow)

metrics:
  - name: monthly_recurring_revenue
    label: Monthly Recurring Revenue
    description: >
      Sum of normalized monthly contract value for all active
      subscriptions at month end. Excludes trials, internal
      accounts, and one-time charges. Uses contract start date,
      not invoice date. Owned by Finance.
    type: simple
    type_params:
      measure: mrr_amount
    filter: |
      {{ Dimension('subscription__status') }} = 'active'
      AND {{ Dimension('subscription__is_trial') }} = false
    meta:
      owner: finance-data@company.com
      reviewed_at: 2026-04-01
      synonyms: [MRR, monthly revenue, monthly arr]

Notice what this definition contains beyond the formula: a plain-language description that explains edge cases, an explicit filter encoding business rules, a named owner, a review date, and synonyms for AI and search resolution.

Design before you build. The most important output of a semantic model design phase is not the YAML files — it is the organisational agreements those files encode. The metric definitions, naming standards, time intelligence decisions, and governance process you put in place now will determine whether your semantic layer becomes a trusted foundation or an expensive source of new confusion. Next issue: the tool comparison — dbt, Cube, AtScale, and Looker assessed honestly, side by side, with no vendor influence.

Next in the series

Tool landscape: dbt, Cube, AtScale, Looker — an honest, vendor-neutral comparison

#TheDataBrief#SemanticLayer#DataModeling#AnalyticsEngineering#dbt#MetricLayer