--- title: "How to Create Databricks Metric Views: YAML, SQL and UI Steps" url: "https://atlan.com/know/ai-agent/semantic-layer/how-to-create-databricks-metric-views/" description: "How to create Databricks metric views: the permissions you need, the Catalog Explorer steps, CREATE VIEW WITH METRICS YAML syntax and MEASURE() queries." author: "Emily Winks" author_role: "Data Governance Expert" published: "2026-10-27" updated: "2026-10-27T00:00:00.000Z" --- > Atlan is hosting Context Conference, bringing together the leaders and builders at the frontier of giving AI the context it needs to understand their business. It runs online on October 28, 2026, from 11:00 AM to 2:00 PM ET. Atlan co-founder Prukalpa Sankar opens and closes the day. Leaders from AstraZeneca, BNY and Verizon share why they invest in context and what they get from it. Registrants get early access to The AI Context Gap, a new study from MIT Technology Review Insights. Register: https://atlan.com/context-conference/ ## How to create Databricks metric views? To create Databricks metric views, write a YAML definition with a source, optional joins and filter, fields and measures, then save it with CREATE VIEW ... WITH METRICS LANGUAGE YAML or build it in the Catalog Explorer editor. You need SELECT on the source, CREATE TABLE and USE SCHEMA on the target schema, and compute on Databricks Runtime 16.4 or above. Anyone with SELECT then queries each measure through the MEASURE() function. Check four permissions first: - **SELECT** on the source table, view or SQL query. - **CREATE TABLE and USE SCHEMA** on the schema that will hold the metric view. - **USE CATALOG** on the parent catalog. - **CAN USE** on a SQL warehouse or cluster. ## Key takeaways - Metric views arrived in Databricks Runtime 16.4, and later features need later runtimes. - Every measure must use an aggregate function. - SELECT * does not work, because each measure needs MEASURE(). - Only the owner can edit the definition. --- To create Databricks metric views, write a YAML definition with a source, optional joins and filter, fields and measures, then save it with `CREATE VIEW ... WITH METRICS LANGUAGE YAML` or build it in the Catalog Explorer editor. You need `SELECT` on the source, `CREATE TABLE` and `USE SCHEMA` on the target schema, and compute on [Databricks Runtime 16.4 or above](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/create). Anyone with `SELECT` then queries each measure through the [`MEASURE()` function](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/query). ### Draft Your Metric View YAML Give it your source table, any tables to join, and the metrics you want. It returns the YAML, the CREATE VIEW statement, and a check against the documented rules. [Read the skill](/skills/metric-view-yaml-drafter.md). *Paste into a new chat* ``` Use the skill at https://atlan.com/skills/metric-view-yaml-drafter.md to draft a Databricks metric view for our metrics. Ask me for whatever it needs. ``` *Run once in a terminal* ``` curl -fsSL --create-dirs \ -o ~/.agents/skills/metric-view-yaml-drafter/SKILL.md \ https://atlan.com/skills/metric-view-yaml-drafter.md ``` *For an agent* ``` curl -fsSL https://atlan.com/skills/metric-view-yaml-drafter.md ``` Human Agent ClaudeChatGPTGeminiCursorOther Copy --- ## What do you need before you create a Databricks metric view? A metric view is a [Unity Catalog object](https://atlan.com/know/ai-agent/semantic-layer/unity-catalog-vs-cross-platform-semantic-layer/) that keeps [measure definitions](https://atlan.com/know/ai-agent/semantic-layer/semantic-layer-vs-metrics-layer/) apart from the fields you group and filter by. A standard view fixes its aggregation at creation; a metric view lets a user group revenue per customer by any field at query time ([Unity Catalog metric views](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/)). Check four permissions first ([Create a metric view](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/create)): - `SELECT` on the source table, view or SQL query. - `CREATE TABLE` and `USE SCHEMA` on the schema that will hold the metric view. - `USE CATALOG` on the parent catalog. - `CAN USE` on a SQL warehouse or cluster. Then check your runtime. Metric views arrived in Databricks Runtime 16.4, and later features need later runtimes ([Metric view feature availability](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/feature-availability)). A SQL warehouse updates itself, so runtimes matter only on clusters. | Databricks Runtime | What it adds | |---|---| | 16.4 | Metric views themselves: create, query, manage | | 17.3 | Snowflake-schema joins, materialization, [agent metadata](https://atlan.com/know/ai-agent/data-for-ai/types-of-metadata-for-ai-agents/) (YAML 1.1), `TEMPORARY` metric views | | 18.0 | BI compatibility mode, `REFRESH MATERIALIZED VIEW` | | 18.1 | One-to-many joins, window `offset`, `rely.at_most_one_match` | | 18.2 | Parameters, wildcard fields (YAML 1.1) | | 19 | Derived column names, windows on a numeric index (YAML 1.1) | --- ## How do you create a metric view in Catalog Explorer? The UI editor builds the YAML for you. Databricks documents a sales example on `samples.tpch.orders`, a table present in every workspace ([Create a metric view](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/create)). The Create page gives Runtime 17.3 as the minimum for this example. The [feature availability table](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/feature-availability) lists `rely.at_most_one_match` at 18.1. 1. **Open the editor.** Click **Catalog**, find `samples.tpch.orders`, then click **Create** > **Metric view**. Name it, pick a catalog and schema, and click **Create**. The editor loads every source column as a field and adds a sample `COUNT(*)` measure. 2. **Add a join.** Select `samples.tpch.customer`, name the join `customer`, set the condition `source.o_custkey = customer.c_custkey`, choose **Many-to-one** and tick **At most one match**. 3. **Add a filter.** Set `source.o_orderdate > '1990-01-01'`. The filter applies to every query on the view. 4. **Keep the fields you need.** Delete the rest, then define Order Month with a month transform, Order Status with a `CASE` expression in **Custom**, and Market Segment from the joined table. 5. **Add measures.** Order Count is `COUNT(1)`, Total Revenue is `SUM(source.o_totalprice)`, and Total Revenue per Customer is `SUM(source.o_totalprice) / COUNT(DISTINCT source.o_custkey)`. 6. **Save.** Preview each field or measure, then click **Save**. Genie Code, in the same editor, drafts a definition from a [plain-language request](https://atlan.com/know/ai-agent/semantic-layer/text-to-sql-vs-semantic-layer-for-self-serve-analytics/) ([Create a metric view](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/create#use-genie-code)) or turns a Tableau or [Power BI file](https://atlan.com/know/ai-agent/semantic-layer/power-bi-semantic-model/) into a metric view ([Use metric views with external BI tools](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/bi-tools)). See where metric definitions sit in the AI context stack A short brief on the layers of context that AI agents read, from metric definitions and lineage to policies. Get the AI Context Stack --- ## How do you create a metric view with SQL and YAML? Wrap the YAML in `CREATE VIEW` with the `WITH METRICS` clause and put it between `$$` delimiters. Here is the documented statement for the sales example on `samples.tpch.orders` joined to `samples.tpch.customer` ([Create a metric view](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/create)): ```sql CREATE OR REPLACE VIEW orders_metric_view WITH METRICS LANGUAGE YAML AS $$ 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 rely: at_most_one_match: true filter: source.o_orderdate > '1990-01-01' fields: - name: Order Month expr: DATE_TRUNC('MONTH', source.o_orderdate) comment: "Month of order" - name: Order Status expr: |- CASE WHEN source.o_orderstatus = 'O' THEN 'Open' WHEN source.o_orderstatus = 'P' THEN 'Processing' WHEN source.o_orderstatus = 'F' THEN 'Fulfilled' END comment: "Status of order" - name: Market Segment expr: customer.c_mktsegment comment: "Customer market segment" measures: - name: Order Count expr: COUNT(1) comment: "Total number of orders" - name: Total Revenue expr: SUM(source.o_totalprice) comment: "Sum of all order prices" - name: Total Revenue per Customer expr: SUM(source.o_totalprice) / COUNT(DISTINCT source.o_custkey) comment: "Average revenue per unique customer" $$ ``` The YAML rules that trip people up ([Metric view YAML syntax reference](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/yaml-reference)): - `version` and `source` are required. You need `fields` or `measures`, or both. - `source` can be a three-part table name, another metric view or a SQL query. - Every measure must use an aggregate function. - Joins are many-to-one `LEFT OUTER JOIN`s by default. `at_most_one_match: true` is not checked at runtime, so a fan-out join returns wrong `SUM` and `COUNT` results. - Wrap any expression that contains a colon, or starts with a backtick, in double quotes. --- ## How do you query a Databricks metric view with MEASURE()? On the `orders_metric_view` sales example, select fields by name and wrap every measure in `MEASURE()` ([Query metric views](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/query)): ```sql SELECT `Order Month`, `Order Status`, MEASURE(`Order Count`), MEASURE(`Total Revenue`) FROM orders_metric_view GROUP BY ALL ORDER BY `Order Month`; ``` `SELECT *` does not work, because each measure needs `MEASURE()`. On Runtime 18.1 and above, `AGG()` works as an alias. You cannot join a metric view directly to another table; aggregate it in a CTE first, then join the CTE. `DESCRIBE TABLE EXTENDED AS JSON` returns the stored YAML in **View Text**. The same view feeds [AI/BI dashboards](https://atlan.com/know/databricks/databricks-ai-bi-genie/), [Genie Agents](https://atlan.com/know/ai-agent/databricks/databricks-genie-context-requirements/) and alerts. [External BI tools](https://atlan.com/know/ai-agent/semantic-layer/semantic-layer-for-analytics/) connect through these routes ([Use metric views with external BI tools](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/bi-tools)): | Route | How it works | Fits | |---|---|---| | Custom SQL | The tool sends the `MEASURE()` query as written | [Power BI native query](https://atlan.com/know/ai-agent/semantic-layer/power-bi-semantic-model-vs-dedicated-semantic-layer/) in DirectQuery mode, Tableau Custom SQL, Sigma, most JDBC or ODBC tools | | Wrapper view | A standard view wraps fixed `MEASURE()` columns | Any tool that reads a Unity Catalog table; one view per dimension set | | BI compatibility mode | Databricks rewrites the tool's `SUM` and `COUNT` into measure logic | Tableau, through the Initial SQL field | | Built-in partner integration | The partner shows [measures and dimensions](https://atlan.com/know/semantic-layer/) natively, without custom SQL | Partners listed under Partner Connect | Find the gaps in your metric context Estimate how much of the context your teams and agents need is missing, and where. Try the Context Gap Calculator --- ## How do you add synonyms, display names and materialization? [Agent metadata](https://atlan.com/know/ai-agent/semantic-layer-for-ai-agents/) needs Runtime 17.3 and YAML version 1.1 ([Agent metadata in metric views](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/agent-metadata)). It adds three things to each field or measure: - `display_name`, up to 255 characters, shown in dashboards instead of the column name. - `synonyms`, up to 10 per field or measure, which [Genie uses to match questions](https://atlan.com/know/ai-agent/databricks/add-context-to-databricks-genie-space/), so "total sales" finds `total_revenue`. - `format`, for number, currency, percentage, byte, date and date-time display. Saving a version 1.1 definition strips `#` YAML comments, so move anything worth keeping into `comment` fields first. Window measures handle rolling and cumulative values. The documented example counts unique customers over a trailing 7 days ([Metric view YAML syntax reference](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/yaml-reference#window-measures)): ```yaml version: 1.1 source: samples.tpch.orders fields: - name: order_date expr: o_orderdate measures: - name: rolling_7day_customers expr: COUNT(DISTINCT o_custkey) display_name: '7-Day Rolling Customers' window: - order: order_date range: trailing 7 day ``` Materialization speeds up queries by pre-computing aggregates. It needs serverless compute and Runtime 17.3 or above ([Materialization for metric views](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/materialization)). You add a `materialization` block with `mode: relaxed`, an optional `schedule` such as `every 6 hours`, and a list of `aggregated` or `unaggregated` materialized views. A managed Lakeflow pipeline builds them, and matching queries reroute automatically. Queries with no match read the source tables directly, so [freshness](https://atlan.com/know/ai-agent/context-freshness/) can differ between two queries on the same view. Without materialization, every query recomputes from source, a cost Daniel Beach calls out in his [walkthrough of metric views](https://dataengineeringcentral.substack.com/p/databricks-semantic-layer-metric). Plan for these limits before you materialize: - No materialization when the view or a source uses row filters, [column masks](https://atlan.com/know/ai-agent/data-for-ai/how-to-handle-pii-in-ai-pipelines/) or [ABAC policies](https://atlan.com/know/ai-agent-access-control/). - `COUNT(DISTINCT)` and window measures serve exact-match queries only, never rollups. - Without a schedule, refresh by hand with `REFRESH MATERIALIZED VIEW `. --- ## How do you grant access to and edit a metric view? A metric view follows the [Unity Catalog permission model](https://atlan.com/know/ai-agent/context-layer/context-layer-role-based-access-control/), so users who already hold SELECT on the parent catalog or schema can query it, because privileges cascade ([Manage metric views](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/manage)). To grant one group query access: ```sql GRANT SELECT ON orders_metric_view to `data-consumers`; ``` Only the owner can edit the definition. In SQL, `ALTER VIEW` with the complete YAML replaces the definition. For team editing, grant a group `SELECT` on every source table and transfer ownership to it. Group ownership does not work for materialized metric views. A `DROP VIEW` cannot be undone, so check the [Lineage tab](https://atlan.com/know/ai-agent/data-for-ai/data-lineage-for-ai/) for dashboards and notebooks that read the view first. Sharing a metric view with another metastore through OpenSharing is in Beta. Advancing Analytics advises [one business area per metric view](https://atlan.com/know/bounded-context-spaces/) and only the joined attributes you need ([Advancing Analytics step-by-step guide](https://www.advancinganalytics.co.uk/blog/how-to-build-a-metric-view-in-databricks-a-step-by-step-guide-for-analysts)). --- ## How does Atlan work with Databricks metric views? Atlan's [Databricks connector](https://atlan.com/know/context-layer-for-databricks/) catalogs each metric view as its own `DatabricksMetricView` asset. It records the view's create statement as the asset definition, shown in the asset profile, and it includes metric views in [lineage tracking](https://atlan.com/know/ai-readiness/ai-ready-data-lineage/) ([What does Atlan crawl from Databricks?](https://docs.atlan.com/apps/connectors/data-warehouses/databricks/references/what-does-atlan-crawl-from-databricks)). [Upstream column lineage](https://atlan.com/know/ai-agent/data-for-ai/automated-sql-lineage-vs-manual-lineage-mapping/) for individual dimensions and measures isn't supported. Lineage from Databricks AI/BI dashboards to the metric views they read is in private preview ([Extract Databricks dashboard lineage](https://docs.atlan.com/apps/connectors/data-warehouses/databricks/how-tos/extract-databricks-dashboard-lineage)). Atlan was a launch partner for Databricks Unity Catalog Metrics at the 2025 Data + AI Summit, and it enriches each metric with [business context](https://atlan.com/know/business-context-for-ai/) and [end-to-end lineage](https://atlan.com/know/mcp/mcp-for-data-lineage/) ([Atlan at Data + AI Summit 2025](https://atlan.com/databricks-summit-2025-announcements/)). It then serves those definitions back to [Genie](https://atlan.com/know/ai-agent/databricks/genie-ontology-and-atlan-context-layer/) and to other agents through [an MCP server](https://atlan.com/know/ai-agent/semantic-layer/mcp-semantic-layer-for-ai-agents/), SQL and [open APIs](https://atlan.com/know/context-api-for-ai/) ([Unity Catalog Metrics and the context layer](https://atlan.com/know/ai-agent/databricks/unity-catalog-metrics/)). General Motors built its Insight Factory on Databricks Unity Catalog and uses Atlan for end-to-end lineage. The GM team has brought time-to-insight down from 28 days to 3 hours ([Databricks Unity Catalog with Atlan](https://atlan.com/databricks-unity-catalog/)). For the wider picture, see [what Unity Catalog's semantic layer covers](https://atlan.com/know/ai-agent/semantic-layer/unity-catalog-semantic-layer/) and [how a metrics catalog connects to Databricks](https://atlan.com/databricks-metrics-catalog/). Watch the WTF is the Context Layer series Live sessions on how teams govern metric definitions, lineage and ownership for AI. Register for the Series Book a Demo --- ## FAQs about Databricks metric views ### Do Databricks metric views replace standard views? No. A standard view still fits a fixed query with fixed groupings. A metric view fits a metric that people slice many ways, such as revenue by month, by segment or by region. It stores the measure once, and the engine computes it for whatever fields the query groups by. ### What is the difference between fields and dimensions in a metric view? None. `fields` and `dimensions` are equivalent keywords, and Databricks now documents `fields` as the preferred term. The Catalog Explorer editor labels the tab Fields but writes `dimensions` into the YAML. One exception: a `materialization` block must list `dimensions:` even when the top-level definition uses `fields:`. ### Can you join a Databricks metric view to another table? Not directly in the query. Joins belong inside the definition, under `joins`, where they run as left outer joins from the source. To combine metric view results with another table at query time, select the measures in a CTE with `MEASURE()` and `GROUP BY`, then join the CTE to the other table. ### Why does SELECT * fail on a metric view? Every measure must be evaluated through the `MEASURE()` aggregate function, and `SELECT *` cannot apply it. List each field by name and wrap each measure, for example ``MEASURE(`Total Revenue`)``, then add `GROUP BY ALL`. On Runtime 18.1 and above, `AGG()` is an accepted alias for `MEASURE()`. ### How do you change a metric view after you create it? The owner edits it in Catalog Explorer, through the UI tab or the YAML editor, or runs `ALTER VIEW` with the complete new YAML. `ALTER VIEW` replaces the whole definition and drops Unity Catalog comments that are not in the YAML `comment` fields. Wildcard fields expand at creation, so recreate the view to pick up new source columns. --- ## Sources 1. [Create a metric view, Azure Databricks documentation on Microsoft Learn](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/create) 2. [Query metric views, Azure Databricks documentation on Microsoft Learn](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/query) 3. [Unity Catalog metric views, Azure Databricks documentation on Microsoft Learn](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/) 4. [Metric view feature availability, Azure Databricks documentation on Microsoft Learn](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/feature-availability) 5. [Use metric views with external BI tools, Azure Databricks documentation on Microsoft Learn](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/bi-tools) 6. [Metric view YAML syntax reference, Azure Databricks documentation on Microsoft Learn](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/yaml-reference) 7. [Agent metadata in metric views, Azure Databricks documentation on Microsoft Learn](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/agent-metadata) 8. [Materialization for metric views, Azure Databricks documentation on Microsoft Learn](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/materialization) 9. [Manage metric views, Azure Databricks documentation on Microsoft Learn](https://learn.microsoft.com/en-us/azure/databricks/uc-semantics/metric-views/manage) 10. [Databricks Semantic Layer: Metric Views, Daniel Beach, Data Engineering Central](https://dataengineeringcentral.substack.com/p/databricks-semantic-layer-metric) 11. [How to Build a Metric View in Databricks: A Step-by-Step Guide for Analysts, Advancing Analytics](https://www.advancinganalytics.co.uk/blog/how-to-build-a-metric-view-in-databricks-a-step-by-step-guide-for-analysts) 12. [What does Atlan crawl from Databricks?, Atlan documentation](https://docs.atlan.com/apps/connectors/data-warehouses/databricks/references/what-does-atlan-crawl-from-databricks) 13. [Extract Databricks dashboard lineage, Atlan documentation](https://docs.atlan.com/apps/connectors/data-warehouses/databricks/how-tos/extract-databricks-dashboard-lineage)