Metrics

Data → Data Catalog → Metrics: a reusable catalog of business metric definitions and their current computed state.

Metrics is where you define the numbers your team runs on, for example revenue, MRR, ROAS, active customers and conversion rate. You define each number once, with a clear definition. Then you use it again everywhere: dashboards, reports, the Agent and the API.

The library itself is a live data table. Each row shows the metric and its computed value over the last 30 days, with an inline sparkline. The row also shows its status, tags and last update. If a metric’s definition cannot be computed at this time, the row shows Not computable instead of a number. The reason shows in a tooltip. You always know if a metric is live or still a work in progress.

Metric calculations

A reusable Metric stores one complete QuerySpec v2 calculation and produces one governed value. The calculation can select a canonical Event, User, Group, Audience, or another Metric. It can apply supported aggregations and filters, or use a formula assembled in Explore.

The saved QuerySpec contains the report type, semantic entities, measures, filters, time range, and a metricOutput that identifies the single value returned by the Metric.

Selecting data

The Calculation section in a Metric starts with a semantic data selector. Choose the Event, User, Group, Audience, or Metric to measure, then choose its aggregation and filters. Use Open in Explore when the calculation needs multiple measures, a formula, or the wider query-building tools. Saving from Explore associates that QuerySpec with the Metric.

Reusable Metrics cannot be authored against physical datasets, tables, or columns. If the needed business concept is missing, create the shaping model in Data Studio and map its output to the semantic layer first. Charts retain their separate model and SQL capabilities.

Filters

The calculation supports filters, so a Metric can target exactly the entities it should count (for example, only active subscriptions or orders above a threshold). Available operators include equals, does not equal, contains, does not contain, greater than, less than, between, is empty, and is not empty.

Measures

The measure controls how the selected semantic data is aggregated:

Running Total (ledger-style metrics)

Most measures answer “what happened within the selected date range?”. Some metrics do not work that way. MRR or active customers answer “what is the balance on date X?”. That balance depends on everything that ever happened, not only the displayed window.

The running total measure exists for exactly this. Point it at a canonical movement Event with a signed delta property (for example, mrr_delta of +49 on upgrade and −49 on churn, or ±1 for customer counts). Vendo then computes the cumulative balance at every date. The date range you select controls which dates are displayed. The accumulation always starts from the beginning of your data. The chart therefore carries the correct balance into the window and holds it steady across days with no activity.

Metrics That Survive Source Changes

The most important design decision in Metrics is that metrics can be defined against canonical events instead of physical tables.

The problem

Traditionally, a metric is welded to a specific table: “sum the amount column in stripe.charges.” Problems start on the day you switch billing systems, restructure a table, or add a second source for the same activity. Every metric that points at the old table then silently breaks or undercounts.

How Vendo solves it

In Vendo, incoming data is mapped to a shared vocabulary through semantic mappings (part of the Data Model). A mapping says: “this table from this source produces the subscription_started event, and here is which column holds the amount, the customer, and the timestamp.”

A metric can then be defined purely in business terms, for example “sum the amount property of the subscription_started event”. The definition has no table or column names. When the metric runs, Vendo looks up which sources currently emit that event. It then resolves the definition to the right tables and columns at that moment. This means:

• One definition works across sources. If both your database and Stripe emit subscription_started, the metric automatically combines them.
• Migrations do not break metrics. Move billing from one platform to another and update the mapping. Every metric that references the event keeps working, and no metric edits are required.
• Failures are loud, not silent. If an event’s mapping is missing the referenced property or a timestamp, the metric is flagged as non-computable and tells you which mapping to fix. It never quietly drops a source or substitutes zero. A number that silently undercounts is worse than no number.

Dates are interpreted in your account’s reporting timezone, so daily buckets match your business calendar.

Calculation details

Every Metric detail drawer includes its Calculation section:

• Semantic input: the Event, User, Group, Audience, or Metric used by the calculation.
• Aggregation and filters: how the input becomes the Metric value.
• Open in Explore: opens the complete QuerySpec in Explore for deeper inspection or editing.
• Format, unit, and direction: controls how the result is displayed and how changes are interpreted.

If a definition cannot be resolved or compiled, the Metric remains a Draft and shows the reason.

Metric Settings

Lifecycle: Draft → Live

A Metric has one of these statuses:

Creating a Metric first saves its name, description, and presentation settings as a Draft. Saving a calculation makes it Live when the server can resolve and compile the QuerySpec. A calculation that cannot compile stays a Draft with the reason. Archived Metrics stay archived until restored. The API and the MCP tools store a Live Metric with the status active.

Change the status

The status control is at the top of the detail drawer. It shows Draft, Live and Archived. You cannot select Archived, and you cannot change the status of an archived Metric.

1. Open the Metric.
2. In the status control, select Live or Draft.

When you select Live, Vendo checks the calculation first. If the calculation cannot be published, the status does not change and the drawer shows the reason.

Verify a Metric

Verification records that a person confirmed the Metric is right. The drawer shows who verified the Metric and when. A verified Metric shows the status Verified in the library.

1. Open the Metric, or open the row menu in the library.
2. Select Verify.

To remove the stamp, select Remove verification. You need write access to Metrics to verify a Metric or remove its verification.

Where Metrics Are Used

• Dashboards — add a metric as a chart or a KPI chart. Values are computed through the same engine as the library table.
• Metric trees — the Metric Trees page lets you arrange metrics into KPI driver trees. The app menu has no link to this page. To open it, add /data/metrics/trees after your workspace in the app URL, for example https://app2.vendodata.com/<workspace>/data/metrics/trees.
• Agent — the Agent can look up, explain, and compute your metrics, so “what is our MRR?” uses your definition, not an improvised query.
• Search and catalog — Live metrics are registered in the Data Catalog and show up in unified search.
• API and MCP — see below.

Creating Metrics

In the app

Go to Data → Data Catalog → Metrics and select Create Metric. Enter the name and plain-language description, then save the Draft. In the detail drawer, select the semantic data for the calculation or choose Open in Explore for a multi-measure calculation.

Define with AI

The Agent can propose the calculation for a Draft Metric. The proposal does not change the saved calculation or the status until a person accepts it.

1. In the library, open the row menu of a Metric that has no calculation.
2. Select Define with AI.
3. Wait for the Agent to finish. The Agent panel opens and starts a new conversation with a prepared message.
4. When the Status column shows Proposal ready, open the Metric.
5. Review the Proposed calculation section.
6. Select Accept or Decline.

Define with AI shows only when the Metric has no complete calculation and no open proposal. Accept shows only when the proposed calculation compiles.

When you accept, Vendo saves the calculation. The Metric becomes Live if the calculation compiles. If it does not compile, the Metric stays a Draft and Vendo shows the reason. When you decline, Vendo discards the proposal and keeps the saved calculation.

A proposal can show one of these results instead of a calculation:

• Needs a Data Studio model first: the Agent shows the model, the semantic mapping and the measure it plans to use. It builds them after you approve in the Agent.
• This metric cannot be expressed with the connected data yet: the proposal gives the reason.

With the Agent or any MCP client

The MCP server exposes the full metric lifecycle as tools. The Agent, and also Claude Code, Cursor and other MCP clients, can manage metrics conversationally:

A typical flow: describe the Metric in plain language (“create an MRR metric from subscription movements”), let the Agent discover the canonical entities and draft the QuerySpec, then review its calculation. The server makes it Live only when the QuerySpec compiles.

Via the API

Metric endpoints live on the Vendo web app and accept your Vendo API key as a Bearer token (the same key used for MCP):

Create and definition-update requests accept a complete QuerySpec v2 in the definition field. The retired metric_type, building_blocks, and formula authoring fields are rejected. Use the saved Metric value endpoint to run a Live Metric. Use Explore to inspect or test a calculation while you edit it.

API keys are account-scoped and rate-limited. See API Authentication for how to create a key.

Comments

The Comments section in the detail drawer holds notes about a Metric from your team.

1. Open the Metric.
2. In Comments, type your comment (5,000 characters or fewer).
3. Select Add comment.

To manage a comment, open its menu. Edit and Delete show only on your own comments.

Warning: Do not select Delete unless you want to lose the comment. Delete removes it permanently, and you cannot undo it.

• Resolve or Reopen: marks the comment as done, or opens it again.
• Edit: changes the text.
• Delete: removes the comment.

Related

• Data Model — how semantic mappings and canonical events are configured.
• Reports — ad insights and cross-channel reporting.
• MCP Server — connect an AI client to manage metrics conversationally.