Skip to content
M↓ View as Markdown ↗

Metrics

Metrics are business calculations built on your models. While measures perform simple aggregations (like counting or summing), metrics encode the calculations your business cares about: conversion rates, averages per customer, churn rates and other KPIs.

Availability

  • Who can do this: members with the Edit capability in the active Workspace can create and edit metrics.

Each metric belongs to one Workspace. Metric names must be unique within that Workspace, and metrics are not shared between Workspaces.

Metrics vs measures

Measures are simple aggregations on a single model.

  • Example: COUNT(DISTINCT customer_id), SUM(revenue)

Metrics are business calculations that may:

  • Combine multiple measures
  • Apply mathematical operations (division, multiplication and so on)
  • Use fields from other models through joins
  • Limit which dimensions, filters and time grains make sense for analysis

Example:

  • Measures: total_revenue (SUM(revenue)) and customer_count (COUNT(DISTINCT customer_id))
  • Metric: total_revenue / NULLIF(customer_count, 0) gives average revenue per customer

Create a metric

  1. In Studio, open Metrics and click New metric.
  2. In Choose a model, select the model the metric is built on. This becomes the metric's Anchor model: "The metric expression is evaluated against this model." Click Next.
  3. In Name the metric, enter:
    • Name: a display name for the metric. It must be unique in the Workspace.
    • Expression (SemQL): the formula that computes the metric. See SemQL expression.
    • Description (optional): what the metric measures.
  4. Click Create metric.

You can then refine the metric on its three tabs: Overview, Calculation and Constraints. Click Save changes to keep your edits.

Note

You can't change the anchor model after you create the metric. To build the same calculation on a different model, create a new metric.

Overview tab

Anchor model

The primary model this metric is built on. The expression is evaluated against this model. Click the model name to open it.

Name

A clear name for this business calculation.

Examples: Average Order Value, Customer Churn Rate, Monthly Recurring Revenue, Conversion Rate

Description

What the metric measures. People see it when they browse metrics.

Example: "Average value of orders placed in the selected time period"

Guidance

Rules for the AI Analyst: when to use this metric and how to query it. Explain:

  • What the metric indicates about your business
  • How to interpret the values
  • When this metric is most useful
  • Any important caveats or limitations

Example: "Indicates customer purchasing power. Higher values suggest premium customer segments. Track over time to understand pricing effectiveness and customer value trends."

Unit

A free-text label shown after the number, for example USD, EUR, % or orders. It does not change the calculation.

Precision

The number of decimal places for the metric's headline value. Leave it empty for no rounding.

Enter a whole number from 0 to 20.

Example: 2 shows 45.32.

Calculation tab

SemQL expression

The formula that computes the metric's headline number, written in SemQL.

Reference dimensions and measures by name, or qualify them with the anchor model's name or a join alias (for example orders.total_revenue or c.customer_id).

  • Measures are already aggregated. Use them bare, for example total_revenue / NULLIF(order_count, 0). Never wrap a measure in SUM() or COUNT(): the expression is refused as a double aggregation.
  • Aggregate functions are for dimensions (raw columns), for example SUM(order_value) where order_value is a dimension.
  • SemQL has no {{ }} templating. An expression that contains braces can't be saved.

Examples:

Division of two measures (total_revenue and order_count are measures on the anchor model):

total_revenue / NULLIF(order_count, 0)

Aggregating dimensions (order_value and id are dimensions on the anchor model):

SUM(order_value) / NULLIF(COUNT(DISTINCT id), 0)

Percentage of two measures (successful_orders and total_orders are measures):

successful_orders / NULLIF(total_orders, 0) * 100

Using a joined model (c is the alias of a join to a customers model, defined under Joins):

total_revenue / NULLIF(COUNT(DISTINCT c.customer_id), 0)

Live validation and preview

As you type, the editor checks the expression against your semantic layer:

  • When the expression is valid, a preview of the headline value appears under it (for example = 8127), calculated from your data.
  • When it is invalid, the editor shows the error. You can't save until you fix it ("Fix the expression error before saving"). Click Fix with Steward to ask Steward to help correct it.

Below the expression, a reference panel lists what you can use. Its tabs are All suggestions, Measures and Functions. An Operators tab appears when there are operators to show. The panel doesn't list dimensions, so type dimension names yourself. Pick an entry to insert it into the expression.

Joins

To use fields from other models, add a join:

  1. On the Calculation tab, under Joins, click Add custom join.
  2. In Linked model, select one of the relationships already defined on the anchor model ("Select a relationship…").
  3. In Alias, enter a short name for the joined model, for example c.
  4. Click Add.
  5. Click Save changes. The join isn't kept until you save.

Use the alias in the expression to refer to the joined model. Join keys and join type come from the relationship, so define or fix relationships on the model first. If the anchor model has no relationships, you'll see "No relationships available on the anchor model."

Each relationship can be used for one join. Once all of the anchor model's relationships are used, Add custom join no longer appears. To change an existing join, use Edit join (the pencil) or Remove join.

Joins that repeat rows

If a join repeats the rows of a model (because the relationship is to-many from that model's side), SUM, COUNT and AVG over that model would be inflated. SemQL refuses these aggregations. COUNT(DISTINCT ...), MIN and MAX are not affected.

Constraints tab

Allowed group-by dimensions

The dimensions the AI Analyst may group by when slicing this metric. Click Add a dimension to add one.

Example: For "Average Order Value", you might allow grouping by:

  • customer_id
  • product_category
  • region

When someone asks "Show me average order value by region", the AI Analyst knows it can use the region dimension.

Why restrict dimensions? Some breakdowns don't make sense. For a "revenue per customer" metric, grouping by individual product SKU would be meaningless. Listing the allowed dimensions prevents misleading analyses.

Filters

Metrics don't have filters of their own. Filters come from the models this metric uses and are edited on those models (see Pre-defined filters).

  • Applied by default: filters set to apply by default on the model. They always apply to this metric, and the AI Analyst can't turn them off. To make a condition always apply, set it as a default filter on the model.
  • Optional: the model's other filters. Click Add a filter to choose which ones the AI Analyst may use when querying this metric. Adding an optional filter doesn't force it to apply.

Time dimension

The date or timestamp dimension used when this metric is shown over time. Pick a DATE or TIMESTAMP dimension from the anchor model or any joined model.

Example: created_at on the orders model.

This tells the AI Analyst which date field to use when someone asks "Show me this metric over time" or "Give me last month's value".

Allowed time grains

The time buckets the AI Analyst may use: hour, day, week, month, quarter or year.

Example: If you select month, quarter and year, the AI Analyst can answer "Show me monthly trends" or "Compare by quarter".

Which AI Analysts can use a metric

You don't grant metric access directly. An AI Analyst can query a metric only if it has access to the metric's anchor model and every model the metric joins. Granting access to models can therefore also grant access to metrics. See Models.

History and deleting metrics

  • Version history: click the Version history button on the metric page to see earlier versions, compare changes and restore a version. See Version history.
  • Delete metric: deleting a metric removes it from the Metrics list and from search. Its name can be reused.

Common metric patterns

The patterns below assume the names used are measures unless noted.

Rates and percentages

What portion of a total meets some condition:

successful_count / NULLIF(total_count, 0) * 100

Examples: success rate, conversion rate, adoption rate

Averages per entity

An average value per customer, user or other entity (entity_id is a dimension):

total_value / NULLIF(COUNT(DISTINCT entity_id), 0)

Examples: revenue per customer, orders per user, transactions per day

Conditional logic

Combine conditions and calculations over dimensions (condition stands for any condition on dimensions):

COUNT(CASE WHEN condition THEN 1 END) / NULLIF(COUNT(*), 0) * 100

Examples: retention rate, qualified lead rate, premium customer rate

Time-based calculations

Restrict a calculation to a recent period (order_date and value are dimensions):

SUM(CASE WHEN order_date >= CURRENT_DATE - INTERVAL '7 days' THEN value END)

SemQL accepts portable analytical SQL. Warehouse-specific spellings such as INTERVAL 7 DAY don't parse: write the interval as a string, for example INTERVAL '7 days'.

Examples: weekly active users, 30-day retention, monthly growth rate

Best practices

  • Build the basic aggregations as measures first, then compose them into metrics. Use a measure when the calculation is a simple aggregation within one model, and a metric when you combine measures, need fields from several models, or want to limit dimensions, filters or time grains.
  • Name metrics the way your business names KPIs. If executives say "customer acquisition cost", don't call it avg_cost_per_new_user.
  • In guidance, say what a high or low value means and what someone should do about it.
  • Allow only dimensions that give meaningful breakdowns.
  • Wrap denominators in NULLIF(..., 0) to avoid division by zero.
  • Use the inline preview while you edit, then ask a few questions after you save to confirm the results.