Skip to content
Monomer

Define a reusable metric

← Model

Use a metric when a calculation should mean the same thing across analyses and dashboards. The app calls an aggregation over a model column an Aggregate metric. Its saved definition still uses a model measure and a simple metric: the measure defines the aggregation, and the metric gives it a reusable business name.

Explorer or higher can read metrics and run them. Creating or editing them needs Editor or higher, plus a model with the required column or existing metrics to use as inputs.

Find and understand a metric

Section titled “Find and understand a metric”

Open Semantics → Metrics, the default tab. The catalog lists each metric’s label and identifier, How it’s calculated (the stored formula, with any metric filter and default grain on a second line), Model, Used in, and Status. Filter by model, calculation type, or status to find the number you need. Status shows only problems: broken references or the absence of a connector that can run the metric. It does not certify the metric’s business meaning.

Select a metric to open its page. Read the author’s description and How it’s calculated, which shows the stored definition as labelled rows: an aggregate’s aggregation, expression, model, and Metric time; a ratio’s or formula’s stored formula followed by each input’s own definition. Slice by groups available dimensions by model and uses their labels when available. A time dimension appears once; select it to open Explore, where you can choose its time grain. Used in shows current Dashboards that select this metric or another metric built from it. The calculation rail follows its tables, models, and inputs; Open map opens Lineage.

The right-hand Status checks the saved definition. Its SQL is collapsed under Show SQL. If the check fails or returns no usable result, Check unavailable offers Retry while the rest of the page remains available.

Create a simple metric

Section titled “Create a simple metric”
  1. Open Semantics → Metrics → New → Metric.
  2. Enter a lower-snake-case Name, such as revenue. Add a clear label and a description explaining inclusions, exclusions, and units.
  3. Choose Add up a column, then the model, column or expression, and aggregation. You can also use an existing aggregate. A model page’s Add aggregate metric starts here with that model selected, and a column’s Use as in the model editor can also create an Aggregate metric.
  4. Add default Filters only if they belong to the metric’s business definition. For example, a completed-order restriction should be explicit and agreed with the team.
  5. Select Save. The metric page opens with the saved definition.
  6. Select Explore to analyze the metric. It opens a query with this metric selected. Choose a connector, time dimension, and a small known reporting period in Explore, then select Run and compare the result to a trusted total.

The metric page explains and checks its definition; execution and results stay in Explore. Show SQL displays the check’s rendered query without running it. A warehouse table that requires a partition date condition may need a bounded period in Explore.

Choose how to calculate it

Section titled “Choose how to calculate it”

The first question is How do you want to calculate it?

Choice in the appSaved typeInputs to prepare
Add up a columnsimple — Aggregate metricModel, column or expression, and aggregation
Divide one metric by anotherratioNumerator and denominator metrics, with their conditions
Write a formularatio for a simple division; otherwise derivedExpression and metric inputs with aliases; offsets for earlier periods
Running total or period to datecumulativeInput metric and window or grain-to-date choice
Conversion between two eventsconversionShared key (entity), base metric, conversion metric, calculation

A formula that divides one input metric by another is saved as a ratio, so its numerator and denominator keep their separate conditions. Other formulas are saved as derived metrics. Running totals, conversions, and offset inputs may need a Calendar table.

Inspect each input metric before composing it. Verify the chosen time dimension and filter semantics with a small query. If an input is missing, create or correct the referenced definition before retrying the analysis.

Create and check a ratio with an agent

Section titled “Create and check a ratio with an agent”

For average order value, first search for and read revenue and order_count to verify that they are existing metrics with compatible business definitions. Describe the advertised metric create and check entries as above. Before saving, call monomer_check with the unsaved ratio definition:

monomer_check input
{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/metrics",
  "action": "check",
  "input": {
    "kind": "METRIC_CHECK",
    "definition": {
      "schemaVersion": 3,
      "name": "average_order_value",
      "type": "ratio",
      "numerator": {"metricName": "revenue"},
      "denominator": {"metricName": "order_count"}
    }
  }
}

Check saves nothing and contacts no warehouse. Review any definition problems before saving; it does not prove the business result. monomer_invoke rejects check. Call monomer_create with the same definition and the create input kind:

monomer_create input
{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/metrics",
  "input": {
    "kind": "METRIC_DEFINITION",
    "definition": {
      "schemaVersion": 3,
      "name": "average_order_value",
      "type": "ratio",
      "numerator": {"metricName": "revenue"},
      "denominator": {"metricName": "order_count"}
    }
  }
}

The ratio uses input metric names, not model measure names or a SQL expression. Read the saved definition and compare a query result with the two component totals. Other definition shapes are described by the metric schema.

To query a single customer, use an existing model dimension of the correct type. Follow the Workspace root to list workspace/explore/runs, then send its advertised SEMANTIC_EXPLORE_RUN entry to monomer_describe before constructing the query. This monomer_invoke example assumes orders.customer_id is a TEXT dimension reachable by the metric, and customer_123 is a known value:

monomer_invoke input
{
  "workspaceId": "0198ef28-2000-7000-8000-000000000001",
  "path": "workspace/explore/runs",
  "action": "run",
  "input": {
    "kind": "SEMANTIC_EXPLORE_RUN",
    "connectorId": "0198ef28-2000-7000-8000-000000000002",
    "query": {
      "schemaVersion": 4,
      "metrics": ["average_order_value"],
      "groupBys": [],
      "metricTimeRange": null,
      "filters": [{"kind": "TEXT", "dimension": {"semanticModelName": "orders", "name": "customer_id"}, "operator": "EQUALS", "values": ["customer_123"]}],
      "orderBy": [],
      "rowLimit": 100
    }
  }
}

Replace the IDs, dimension, and customer value with verified values. If the model exposes a NUMBER customer dimension, use kind: "NUMBER" and canonical decimal strings in values, such as ["123"]. Semantic query filters use a typed dimension object and a values array; consult the query schema for other types and operators. This example leaves the reporting period unset. To make customer selection interactive, connect a Dashboard variable to the query filter.

Edit a shared metric

Section titled “Edit a shared metric”

Select Edit on the metric page to change its definition in place. Review Affects if saved, which lists dependent definitions and current Dashboard usage, before selecting Save. The impact list is also used in the delete dialog. The editing Check shows SQL and explains that check problems do not block saving. An unavailable check can be retried. Subsequent queries use the saved definition, so a calculation change can affect their results. After saving, select Explore to verify the change with the metric selected.

Choose a display format

Section titled “Choose a display format”

A metric can have an optional Display format. Default keeps the automatic number display. Number, Currency, and Percent apply to all five calculation types and use 0–6 decimal places. Currency requires an ISO 4217 currency code; Number can include a unit such as seconds, bytes, or percent. Aggregates created while saving a model start with Default; edit the saved metric to choose a format.

Percent treats the stored value as a ratio: 0.125 displays as 12.50% with two decimals. Number with the percent unit only adds the suffix: 12.5 displays as 12.50%. Choose the form that matches the calculation’s stored value.

Monomer uses the exact decimal string to format results. A nonzero value that would round to zero expands beyond the chosen decimal places, up to 20, so a small result stays visible. If it still cannot show a nonzero value within that bound, the table shows the exact raw decimal; Percent shifts the raw decimal two places before adding %.

For an agent, describe the advertised create or EDIT entry before constructing the input. Include "display": {"style": "CURRENCY", "decimals": 2, "currency": "USD"} in a metric definition, or patch /display on an existing metric. Use {"style":"PERCENT","decimals":2} for ratios, or {"style":"NUMBER","decimals":2,"unit":"percent"} for numbers already expressed as percentages. Omit display, set it to null, or remove it to return to Default. The display schema lists the supported currency codes and units.

Explore and Dashboard runs capture the display format when they are created. An existing or reused result keeps that format after the metric is edited; a new run captures the new choice. Explore, Monomer-rendered Dashboard tables and charts, and Public Pages use this saved metadata. Formatting changes the presentation only: exact result values, Arrow downloads, and CSV exports stay unchanged. SQL result columns use the automatic number display.

History, delete, and restore

Section titled “History, delete, and restore”

Every create, edit, and delete keeps the complete metric definition in History, with the person, time, and whether they used the Web app or an agent app. Explorer or higher can read History; Editor or higher can delete or restore a version.

Open the metric’s actions and select Delete. Review the dependent metrics and the warning that dashboards and pages using this metric stop updating, then type its name to confirm. References stay in place: dependent queries can fail with the missing definition named. Existing Explore runs and their results remain available.

A deleted item in Activity opens its History with a Deleted state. Select Restore on the Deleted entry to restore the last recorded definition. Older versions with different content offer Restore this version. Older entries with the same content as the latest recorded definition have no restore control. The newest entry of a live definition also has no restore control. A deleted definition returns with its original ID. If a different definition already uses that name, restore is rejected; resolve the name conflict before trying again. Creating a new definition with a reused name gives it a new ID and separate History. History is retained when a definition is deleted and cannot be deleted from this screen.