Metrics
Combine a measure with a time column into a queryable time-series metric for dashboards and APIs.
A metric is the primary interface that consumers and dashboards use. It takes a measure from a semantic model, adds a time column and a default granularity, and turns it into one queryable time series.
Define one metric per file, in models/metrics/. Defining a metric once is how every dashboard, report, and AI agent ends up using the same definition of a number.
The shape
The smallest valid metric needs 4 fields:
kind: metric
name: daily_sales_performance
measure: daily_sales.total_daily_revenue
ts: daily_sales.order_date
granularity: dayThe full form adds grouping dimensions, segments, and discovery metadata:
kind: metric
name: daily_sales_performance
measure: daily_sales.total_daily_revenue
ts: daily_sales.order_date
granularity: day
dimensions:
- name: region
ref: daily_sales.region_name
- name: category
ref: daily_sales.category
segments:
- daily_sales.high_revenue_days
description: Daily revenue trends by region and category.
tags:
- sales
- revenueEvery metric needs:
kind: metrica unique
namea
measure, referencingsemantic.measurea
tstime column, referencingsemantic.columna
granularity, fromsecondthroughyear
measure and ts must point at different references.
What the parts do
measureis the number to compute, from a semantic model.tsis the time axis for the series.granularityis the default bucket. Consumers can override it at query time, so you don't need separate daily, weekly, and monthly metrics for the same measure.dimensionslet consumers slice the metric. Use a bare reference (daily_sales.region_name) to derive the name, or a named slice (name+ref) when you want a different display name, when two columns would collide, or when you want to override that field'sdescription,tags,terms, orai_contextfor this metric only.segmentsapply predefined filters from the semantic model by reference. Unlike dimensions, segment entries must be plain qualified-ref strings: no per-entry metadata; edit the segment on its semantic model instead.tagsandtermsmake the metric discoverable in the Data Product Hub.
Cross-model metrics
A metric can draw its measure, time column, and dimensions from different semantic models, as long as the models are connected through joins. By default (join_path: directed), the path must follow outgoing join edges starting from the measure's anchor model. A reference reachable only by walking a join backwards fails validation. Set join_path: connected on the metric (or metric_join_path: connected project-wide) to allow any path regardless of direction; this is common when the only usable path runs against a reciprocal join's non-BI-facing side.
customer_lifetime_value is an example. It takes its measure and dimensions from customer_profile, which already joins to the underlying silver models.
Validation and legacy keys
Running vulcan plan checks that:
the
measureandtsreferences are validthe
granularityis recognizeddimension and segment references resolve
cross-model join paths exist, per the effective
join_pathmode
Two old keys are rejected: use ts instead of time, and dimensions instead of slices.
measure, time, and ts are reserved: you can't use them as a dimension name or as a segment's auto-derived name (<semantic_name>_<segment_name>).
For the full reference, including join-path resolution, see References → Vulcan → Models → Business metrics.
With assets in place, make the product enforce its own contract: Data quality, Assertions, and Unit Test.
Last updated
Was this helpful?