Metrics Library

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

The Metrics Library is where you define the numbers your team actually runs on — revenue, MRR, ROAS, active customers, conversion rate — once, with a clear definition, and then reuse them everywhere: dashboards, reports, the Agent, and the API.

The library itself is a live data table. Each row shows the metric alongside its computed value over the last 30 days with an inline sparkline, plus its status, type, category, formula, and last update. Metrics whose definition can’t currently be computed show the reason instead of a number, so you always know whether a metric is real or still a work in progress.

Metric Types

There are two kinds of metrics:

Building Blocks

Composed metrics are built from labeled blocks (A, B, C, …) combined with a formula using + - * / and parentheses — for example A / B * 100.

Each block is one input to the formula. A block can be:

• An existing metric — reuse a metric you already defined, so definitions compose instead of being copy-pasted.
• A custom query — pick a data source, a table or event, a field, a measure (how to aggregate), and optional filters.

Filters

Each block supports row-level filters so a metric can target exactly the rows it should count — for example, only status = active subscriptions, or only orders above a threshold. Available operators: equals, does not equal, contains, does not contain, greater than, less than, between, is empty, is not empty.

Measures

The measure controls how a block aggregates rows:

Running Total (ledger-style metrics)

Most measures answer “what happened within the selected date range?”. Some metrics don’t work that way — MRR or active customers answer “what is the balance on date X?”, where the balance depends on everything that ever happened, not just the displayed window.

The running total measure exists for exactly this. Point it at a movement ledger — a table with one row per change and a signed delta column (e.g., mrr_delta of +49 on upgrade and −49 on churn, or ±1 for customer counts) — and Vendo 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, so the chart 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 the Metrics Library 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.” The day you switch billing systems, restructure a table, or add a second source for the same activity, every metric pointing at the old table 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 — “sum the amount property of the subscription_started event” — with no table or column names in the definition. When the metric runs, Vendo looks up which sources currently emit that event and 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 don’t break metrics. Move billing from one platform to another, update the mapping, and every metric that references the event keeps working — no metric edits 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.

Blocks can still reference a literal table and column directly when you need an escape hatch for data the semantic layer doesn’t cover. Dates are interpreted in your account’s reporting timezone, so daily buckets match your business calendar.

How It’s Calculated

Every metric detail page includes a “How it’s calculated” panel, so a metric is never a black box:

• Per-block definition — the aggregation, source table, and filter conditions for each building block.
• The formula — how the blocks combine.
• The exact SQL — the generated BigQuery query, copyable, produced by the same engine that computes the displayed values, so the explanation can never drift from what actually runs.
• Lineage links — when a block reads from a view produced by a data transformation, the panel links to that model’s page.

If a metric’s definition is broken, the panel shows the compile error instead of SQL.

Metric Settings

Lifecycle: Draft → Active

Metrics have three statuses:

In the builder, Save as Draft stores the definition without publishing it, and Save & Activate publishes in one step. You can preview a metric’s chart while building, before saving anything.

Where Metrics Are Used

• Dashboards — add a metric as a chart or KPI widget; values are computed through the same engine as the library table.
• Metric trees — the Trees view inside the Metrics Library lets you arrange metrics into KPI driver trees.
• Agent — the Agent can look up, explain, and compute your metrics, so “what’s our MRR?” uses your definition, not an improvised query.
• Search and catalog — active 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. The builder walks you through picking blocks, choosing measures and filters, writing the formula, and previewing the resulting chart before you save.

With the Agent or any MCP client

The MCP server exposes the full metric lifecycle as tools, so the Agent — or 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 the subscription ledger”), let the Agent draft it, review the definition and the “How it’s calculated” SQL, then activate.

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

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

Related

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