Unity Catalog Metric Views
Define reusable, governed business metrics in YAML that separate measure definitions from dimension groupings for flexible querying.
When to Use
Use this skill when:
- Defining standardized business metrics (revenue, order counts, conversion rates)
- Building KPI layers shared across dashboards, Genie, and SQL queries
- Creating metrics with complex aggregations (ratios, distinct counts, filtered measures)
- Defining window measures (moving averages, running totals, period-over-period, YTD)
- Modeling star or snowflake schemas with joins in metric definitions
- Enabling materialization for pre-computed metric aggregations
Prerequisites
- Databricks Runtime 17.2+ (for YAML version 1.1); 17.3+ for semantic metadata (
synonyms / display_name / format)
- SQL warehouse with
CAN USE permissions
SELECT on source tables, CREATE TABLE + USE SCHEMA in the target schema
Metric View Lifecycle
| Task |
Reference |
Load when |
| Create |
metric-view-advisor.md |
Any creation task — the advisor handles the full workflow (profile schema, analyze sources, suggest, deploy). Load create-patterns.md alongside as the YAML spec and pattern reference. |
| YAML spec / patterns |
create-patterns.md |
Patterns 1–12, full YAML field reference, formatting gotchas, deployment errors, quick reference. Companion to the advisor; also load directly for pattern lookup. |
| Query |
query-patterns.md |
Writing SQL against a metric view — MEASURE() basics, filters, join rollups, window measures, Rules 1–3. |
| Genie integration |
metric-view-advisor.md §Genie Design Rules |
One-fact-source rule, base views, domain organization, naming. Agent metadata fields (comment, synonyms, display_name, format) are in create-patterns.md §YAML Field Reference. |
Typical flow: advisor → create → query/validate → Genie integration (if adding to a Genie Agent).
Source-controlled deployment with Declarative Automation Bundles
To source-control a metric view, commit its complete SQL definition and execute it through a bundle-managed SQL job. DABs do not have a native metric-view resource, but a bundle-managed SQL job can apply a committed definition:
# databricks.yml
bundle:
name: orders_metrics
variables:
catalog: { default: main }
schema: { default: default }
warehouse_id: { default: "" }
resources:
jobs:
deploy_orders_metrics:
name: deploy_orders_metrics
parameters:
- name: catalog
default: ${var.catalog}
- name: schema
default: ${var.schema}
tasks:
- task_key: create_metric_view
sql_task:
warehouse_id: ${var.warehouse_id}
file:
path: ../src/orders_metrics.metric_view.sql
Deploy and run:
databricks bundle deploy --target <TARGET> --profile <PROFILE>
databricks bundle run deploy_orders_metrics --target <TARGET> --profile <PROFILE>
See the official metric view bundle example.
Related Skills
- databricks-genie-agents — create, manage, and validate Genie Agents that consume the metric views built here. Metric-view design rules for Genie are in the advisor §Genie Design Rules; query rules are in query-patterns.md.
- databricks-aibi-dashboards — build AI/BI dashboards on top of metric views.
- databricks-data-discovery — explore data before creating metric views; answer questions across your workspace.
- databricks-dabs — source-control and deploy metric view SQL definitions via bundle-managed jobs.
Resources
1---2name: databricks-metric-views3description: Unity Catalog metric views: define, create, query, and manage governed business metrics in YAML. Use when building standardized KPIs, revenue metrics, order analytics, or any reusable business metrics that need consistent definitions across teams and tools.4---5
6# Unity Catalog Metric Views
7
8Define reusable, governed business metrics in YAML that separate measure definitions from dimension groupings for flexible querying.
9
10## When to Use
11
12Use this skill when:
13- Defining **standardized business metrics** (revenue, order counts, conversion rates)
14- Building **KPI layers** shared across dashboards, Genie, and SQL queries
15- Creating metrics with **complex aggregations** (ratios, distinct counts, filtered measures)
16- Defining **window measures** (moving averages, running totals, period-over-period, YTD)
17- Modeling **star or snowflake schemas** with joins in metric definitions
18- Enabling **materialization** for pre-computed metric aggregations
19
20## Prerequisites
21
22- **Databricks Runtime 17.2+** (for YAML version 1.1); **17.3+** for semantic metadata (`synonyms` / `display_name` / `format`)
23- SQL warehouse with `CAN USE` permissions
24- `SELECT` on source tables, `CREATE TABLE` + `USE SCHEMA` in the target schema
25
26## Metric View Lifecycle
27
28| Task | Reference | Load when |
29|------|-----------|-----------|
30| **Create** | [metric-view-advisor.md](references/metric-view-advisor.md) | Any creation task — the advisor handles the full workflow (profile schema, analyze sources, suggest, deploy). Load [create-patterns.md](references/create-patterns.md) alongside as the YAML spec and pattern reference. |
31| **YAML spec / patterns** | [create-patterns.md](references/create-patterns.md) | Patterns 1–12, full YAML field reference, formatting gotchas, deployment errors, quick reference. Companion to the advisor; also load directly for pattern lookup. |
32| **Query** | [query-patterns.md](references/query-patterns.md) | Writing SQL against a metric view — `MEASURE()` basics, filters, join rollups, window measures, Rules 1–3. |
33| **Genie integration** | [metric-view-advisor.md §Genie Design Rules](references/metric-view-advisor.md#genie-design-rules) | One-fact-source rule, base views, domain organization, naming. Agent metadata fields (`comment`, `synonyms`, `display_name`, `format`) are in [create-patterns.md §YAML Field Reference](references/create-patterns.md#yaml-field-reference). |
34
35Typical flow: **advisor → create → query/validate → Genie integration (if adding to a Genie Agent)**.
36
37### Source-controlled deployment with Declarative Automation Bundles
38
39To source-control a metric view, commit its complete SQL definition and execute it through a bundle-managed SQL job. DABs do not have a native metric-view resource, but a bundle-managed SQL job can apply a committed definition:
40
41```yaml
42# databricks.yml
43bundle:
44 name: orders_metrics
45
46variables:
47 catalog: { default: main }
48 schema: { default: default }
49 warehouse_id: { default: "" }
50
51resources:
52 jobs:
53 deploy_orders_metrics:
54 name: deploy_orders_metrics
55 parameters:
56 - name: catalog
57 default: ${var.catalog}
58 - name: schema
59 default: ${var.schema}
60 tasks:
61 - task_key: create_metric_view
62 sql_task:
63 warehouse_id: ${var.warehouse_id}
64 file:
65 path: ../src/orders_metrics.metric_view.sql
66```
67
68Deploy and run:
69
70```bash
71databricks bundle deploy --target <TARGET> --profile <PROFILE>
72databricks bundle run deploy_orders_metrics --target <TARGET> --profile <PROFILE>
73```
74
75See the official [metric view bundle example](https://github.com/databricks/bundle-examples/tree/main/knowledge_base/metric_view).
76
77## Related Skills
78
79- **[databricks-genie-agents](../databricks-genie-agents/SKILL.md)** — create, manage, and validate Genie Agents that consume the metric views built here. Metric-view design rules for Genie are in the [advisor §Genie Design Rules](references/metric-view-advisor.md#genie-design-rules); query rules are in [query-patterns.md](references/query-patterns.md).
80- **[databricks-aibi-dashboards](../databricks-aibi-dashboards/SKILL.md)** — build AI/BI dashboards on top of metric views.
81- **[databricks-data-discovery](../databricks-data-discovery/SKILL.md)** — explore data before creating metric views; answer questions across your workspace.
82- **[databricks-dabs](../databricks-dabs/SKILL.md)** — source-control and deploy metric view SQL definitions via bundle-managed jobs.
83
84## Resources
85
86- [Metric Views Documentation](https://docs.databricks.com/metric-views/)
87- [YAML Syntax Reference](https://docs.databricks.com/metric-views/data-modeling/syntax)
88- [Joins](https://docs.databricks.com/metric-views/data-modeling/joins)
89- [Window Measures](https://docs.databricks.com/metric-views/data-modeling/window-measures) (Experimental)
90- [Materialization](https://docs.databricks.com/metric-views/materialization)
91- [MEASURE() Function](https://docs.databricks.com/sql/language-manual/functions/measure)
gabrielmoreira