Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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: day

The 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
  - revenue

Every metric needs:

  • kind: metric

  • a unique name

  • a measure, referencing semantic.measure

  • a ts time column, referencing semantic.column

  • a granularity, from second through year

measure and ts must point at different references.

What the parts do

  • measure is the number to compute, from a semantic model.

  • ts is the time axis for the series.

  • granularity is 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.

  • dimensions let 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's description, tags, terms, or ai_context for this metric only.

  • segments apply 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.

  • tags and terms make 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 measure and ts references are valid

  • the granularity is recognized

  • dimension and segment references resolve

  • cross-model join paths exist, per the effective join_path mode

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?