Databricks Semantic Layer: Build It With Metric Views

A Databricks semantic layer cuts what Genie has to improvise: define your KPIs in Unity Catalog metric views, put the remaining rules where they belong, and prove the effect with a benchmark built on gold SQL. The engine then computes the formula, and the model's job shrinks to choosing what to ask for. In a 2026 preprint, researchers at Cube, a semantic layer vendor, added a 4 KB markdown semantic document to text-to-SQL on ClickHouse and gained 17 to 23 percentage points, "by changing what the model is being asked to do." That test did not involve Genie, so treat it as a direction and measure your own case.

What the Databricks Semantic Layer Is, and What It Is Actually Called

A Databricks semantic layer is the set of governed business definitions, built mainly from Unity Catalog metric views, that dashboards, SQL and Genie read instead of recalculating a KPI in each tool.

Databricks sells no product under that name. Its April 2026 announcement says Unity Catalog Business Semantics, while the documentation says Unity Catalog semantics. The parts are metric views, domains, Pages and certification, and the docs call Databricks metric views "the core implementation of Unity Catalog semantics."

Databricks metric views entered Public Preview on May 29, 2025, and Databricks announced general availability on April 2, 2026. Genie Spaces became Genie Agents on July 8, 2026, so older guides use the old name. Unity Catalog semantics forms "the human-modeled layer of the Genie Ontology," and the rest of that ontology is inferred. Genie Ontology is in Public Preview at the time of writing.

This is a build guide, not a product tour. For what Databricks announced around its context layer, see what the summit put on the table for agents. Grain and conformed dimensions are assumed: they come before any metric definition.

Why Genie Guesses Without One

Genie selects "relevant names and descriptions from annotated tables and columns" to write its SQL. A schema does not know what your company calls revenue. Without a Databricks semantic layer, that meaning comes from column names and whatever instructions someone wrote.

Two public tests of a semantic layer for AI point the same way. In the Cube preprint, about 100 questions on ClickHouse scored 45.5% to 50.5% without the document and 67.7% to 68.7% with it, across three models. dbt Labs, which sells a semantic layer, reports 11 questions on its ACME Insurance project, each run 20 times on the same modeled data: Claude Sonnet 4.6 went from 90.0% with text-to-SQL to 98.2% through the Semantic Layer, and GPT-5.3 Codex from 84.1% to 100.0%. Both companies sell this category, each test uses one dataset, and neither touches Genie or Databricks metric views. Cube's paper covers "the context form of the semantic layer specifically," so the runtime form stays open.

dbt Labs also describes how things break: "With text-to-SQL, failure looks like a plausible but incorrect answer. With the Semantic Layer, failure looks like an error message." For a KPI, that matters more than a percentage point. A plausible wrong number can reach a board deck, while an error message stops at the person who asked.

The Four Guesses a Semantic Layer Has to Remove

In our framing, an AI analyst guesses in four places, and a Databricks semantic layer handles each one differently:

• The formula. Is revenue per customer a sum over distinct customers or an average of averages? A measure in a metric view settles it.
• The join. Which path, and at what cardinality? The joins block settles it. Foreign keys in Unity Catalog help too, and relationships between metric views, in Beta as of the documentation in November 2026, add join metadata.
• The word. Does sales mean revenue, and is FL the same as Florida? Synonyms and entity matching narrow it.
• The window. Which fiscal year, what counts as last quarter, which default filter? The filter field and a text instruction about the calendar narrow it too.

The first two guesses disappear by construction, and the other two only narrow. The documentation says Genie works "in a nondeterministic manner," so in our reading the engine compiles a definition the same way every time, while choosing the measure, filter and grouping stays a model decision.

A Worked Metric View, Line by Line

The smallest useful Databricks semantic layer is one metric view. The metric view YAML below is adapted from the Databricks tutorial and its agent metadata page, and it reads the samples.tpch tables, "available in every workspace."

version: 1.1
comment: 'Orders KPIs for sales analysis'
source: samples.tpch.orders
joins:
  - name: customer
    source: samples.tpch.customer
    'on': source.o_custkey = customer.c_custkey
filter: source.o_orderdate > '1990-01-01'
fields:
  - name: Order Month
    expr: DATE_TRUNC('MONTH', source.o_orderdate)
    comment: 'Month of order'
    synonyms: ['order time', 'date of order']
  - name: Market Segment
    expr: customer.c_mktsegment
    comment: 'Customer market segment'
    synonyms: ['segment', 'customer tier']
measures:
  - name: Total Revenue
    expr: SUM(source.o_totalprice)
    comment: 'Sum of all order prices'
    synonyms: ['revenue', 'total sales']
  - name: Total Revenue per Customer
    expr: SUM(source.o_totalprice) / COUNT(DISTINCT source.o_custkey)
    comment: 'Average revenue per unique customer'
    synonyms: ['revenue per customer']

version: 1.1 is what allows synonyms, and agent metadata also needs Databricks Runtime 17.3. The filter "applies to all queries that reference the metric view." A join has to be many-to-one: in a many-to-many case Databricks takes "the first matching row," so check cardinality first.

Total Revenue per Customer is the measure to study. A ratio cannot be rolled up from a stored aggregate, so the view keeps the expression and "The query engine generates the correct computation" for any grouping. comment and synonyms are written for the agent. Synonyms are "automatically imported to help Genie better discover and understand available fields and measures." That helps discovery, with no guarantee of a match.

To query the view, use the MEASURE function: "All measure evaluations in a metric view query must use the MEASURE aggregate function."

SELECT
  `Market Segment`,
  MEASURE(`Total Revenue per Customer`)
FROM orders_metric_view
GROUP BY ALL;

You can save Databricks metric views through the editor in Catalog Explorer, or in SQL, where you wrap the YAML in a CREATE VIEW ... WITH METRICS LANGUAGE YAML statement.

Where Each Business Rule Belongs

Genie reads business logic from five homes, and the documentation spreads them across two products. A Databricks semantic layer holds the rules that travel across the catalog, while the rest stay inside one agent.

This table is our rule of thumb, not a Databricks standard. One test decides when a definition moves: the second consumer. It starts in the knowledge store while it serves one agent, and goes to a metric view when another agent, a dashboard or a notebook needs it. Knowledge store configurations are "scoped to your Genie Agent," and the move is cheap: "You can export the context from a Genie Agent as a metric view."

Inside an agent, prefer SQL to prose, because "Genie applies the logic exactly as written rather than interpreting it from natural language." The docs say to "Use text instructions only as a last resort." Each agent gets 100 instructions and 200 knowledge store snippets.

Prove It: A Genie Benchmark Before and After

We found no public, controlled benchmark of Genie with metric views, so your own run is the number that counts. Genie has a built-in benchmark feature, where "accuracy is assessed by comparing the result set from your SQL query to the one generated by Genie." Our protocol uses it in five steps:

1. Collect the questions the business asks most, with two to four phrasings of each.
2. Write gold SQL for every question, meaning the query whose result is the correct answer.
3. Run the benchmark in Chat mode on an agent built on tables, and record the result.
4. Attach the metric view, keep the agent to five or fewer objects, and run the same set.
5. Compare question by question, because an aggregate score hides the misses. Assign each mismatch to one of the four guesses and fix it in the home from the table.

Without gold SQL, scoring falls back on people: "Any questions that do not include a SQL Answer require manual review to be scored." One agent holds up to 500 benchmark questions. We attach no expected gain to this protocol, because the result depends on your schema and questions.

Limits to Plan For, and Where to See It Live

Before a Databricks semantic layer reaches business users, plan for these limits, listed as of the documentation in November 2026:

• Queries on Databricks metric views must name individual columns, with no SELECT *, and the views "cannot be directly joined with other tables at query time." Use a CTE.
• ALTER VIEW "replaces the full definition" and only the owner can edit, so hand ownership to a group. Materialized metric views cannot make that transfer.
• YAML 1.1 removes # comments on save, so keep the definition in a repo.
• The at_most_one_match property "is not validated at runtime." Check uniqueness yourself.
• Power BI: BI compatibility mode has left the connector, so use MEASURE() in a Native query.
• A metric view over row filters or column masks cannot be materialized, and a row filter excludes the table from prompt matching.

To see this live, join the online webinar on November 18 at 3:00 PM CET, where Databricks, DS Stream and PayPo will show data context in practice, including a live Metric Views demo. The webinar is in Polish: register on the Databricks event page.

Treat a metric definition like code, kept in a repo and tested against gold SQL. That is how we deliver on Databricks. To start, bring us the one KPI your teams keep recalculating.

FAQ

What is the Databricks semantic layer called?

It has no official product name in those words. The Databricks blog says Unity Catalog Business Semantics, and the documentation says Unity Catalog semantics. Metric views are the core of both.

How are Databricks metric views different from standard views?

A standard view fixes its grouping when you write it. A metric view stores the measure on its own, so the engine computes it for whatever grouping a query requests, and the query calls MEASURE().

Can Power BI use metric views?

Yes, through a Native query with MEASURE() in DirectQuery, or through a wrapper view. BI compatibility mode is no longer available in the Power BI connector, as of the documentation in November 2026.

Does a semantic layer guarantee correct Genie answers?

No. A Databricks semantic layer fixes how a metric is computed, while choosing the metric, filter and grouping stays a model decision. Questions outside the model have no coverage: dbt Labs notes that "the Semantic Layer can only answer questions that fall within the scope of what's been modeled."