Metrics in Collate

The Metrics entity in Collate lets you define, document, and manage key business and operational metrics. Metrics help your organization maintain consistency, traceability, and accuracy in data-driven decision-making.

Overview of Metrics

Metrics document calculated values based on data assets. Collate lists them under the Governance section. You can link each metric to:

Glossary terms
Data assets
Other metrics

These links show how the metric relates to your data quality and usage.

What a Metric Stores

A metric lets you document and share a business metric’s definition. It includes:

Name: The metric’s unique identifier.
Meaning: A description of what the metric measures.
Calculation: The formula or SQL used to calculate it.

Calculation and Scheduling

Keep the following in mind about how metrics work:

No calculation or scheduling: Collate stores the metric’s definition. It doesn’t compute or schedule the metric’s values on its own.
Collate AI: Collate AI can run a saved metric’s SQL against your connected database when it answers a question. For more information, see Context Engineering.
Your own tools: You can also calculate the value in your database or business intelligence (BI) tool and record it here so everyone can find it.

If you want Collate to track how many of your tables and other data assets have a description or an owner, use Key Performance Indicators (KPIs). Data Insights calculates them for you.

Key Properties of a Metric

Property	Description	Example Value
Name	Unique identifier for the metric, following camelCase naming conventions.	`customerRetentionRate`
Display Name	Human-readable name for the metric.	`Customer Retention Rate`
Description	Detailed explanation of what the metric represents.	`Percentage of retained users`
Expression	Formula or SQL that documents how the metric is calculated.	`COUNT(returning_customers)`
Granularity	Time scale for the metric, such as daily, weekly, or monthly.	`Daily`
Metric Type	Type of calculation the metric’s definition describes, such as count, average, or ratio.	`Percentage`
Unit of Measurement	Unit for interpreting metric values, such as count, dollars, or percentage.	`Percentage`
SQL Query	Optional SQL that documents the metric’s definition.	`SELECT COUNT(*) FROM sales`
Owner	Individual or team responsible for maintaining the metric.	`Data Governance Team`

Metric Lineage and Dependencies

Use Collate to trace the source and dependencies of metrics using lineage. This ensures end-to-end traceability from raw data to metric reporting. A typical lineage might look like:

Database Table → Metric → Pipeline → Dashboard

View associated tables, pipelines, and dashboards to understand how each metric is defined and where it’s used.

Creating Metrics Using the UI

To create a new metric in Collate using the user interface, follow these steps:

From the left navigation bar, navigate to Governance > Metric.
Click Add Metric.

Fill in the following fields:
- Name (required): Enter a unique identifier for the metric, using camelCase without spaces (for example, customerRetentionRate).
- Display Name (Optional): Enter a human-readable name displayed in the UI (for example, Customer Retention Rate).
- Description (Optional): Describe what the metric measures and how it is used.
- Granularity (Optional): Select the time scale for the metric — for example, Daily, Weekly, or Monthly.
- Metric Type (Optional): Select the type of calculation — for example, Count, Average, or Percentage.
- Language (Optional): Select the programming language for the metric expression — for example, SQL, Python, or Java.
- Measurement Unit (Optional): Select the unit used to interpret the metric value — for example, Count, Percentage, or Dollar.
- Code (Optional): Enter the formula or query that documents how the metric is calculated, in the selected language.
Click Create to save the metric.
The newly created metric appears in the Metrics page.

Example JSON for Creating a Metric

The following request body creates a metric with POST /v1/metrics. Only name is required. The related metric must already exist, and the id values are examples that you replace with your own.

{
  "name": "customerRetentionRate",
  "displayName": "Customer Retention Rate",
  "description": "Percentage of customers retained over a given period.",
  "metricExpression": {
    "language": "SQL",
    "code": "SELECT 100.0 * COUNT(DISTINCT CASE WHEN is_returning THEN customer_id END) / COUNT(DISTINCT customer_id) FROM customer_activity"
  },
  "metricType": "PERCENTAGE",
  "unitOfMeasurement": "PERCENTAGE",
  "granularity": "MONTH",
  "relatedMetrics": [
    "customerChurnRate"
  ],
  "owners": [
    {
      "id": "7c5a3f1e-2b4d-4e6a-9c8b-1d2e3f4a5b6c",
      "type": "team"
    }
  ],
  "reviewers": [
    {
      "id": "0f9e8d7c-6b5a-4c3d-8e2f-1a0b9c8d7e6f",
      "type": "user"
    }
  ],
  "tags": [
    {
      "tagFQN": "PII.NonSensitive",
      "source": "Classification",
      "labelType": "Manual",
      "state": "Confirmed"
    }
  ]
}

Field	Description
`metricExpression`	The calculation, as an object with a `language` (`SQL`, `Java`, `JavaScript`, `Python`, or `External`) and the `code`. Collate stores the expression. It doesn’t compute or schedule the metric’s values.
`metricType`	The type of calculation, such as `COUNT`, `SUM`, `AVERAGE`, `RATIO`, or `PERCENTAGE`.
`unitOfMeasurement`	The unit, such as `COUNT`, `DOLLARS`, or `PERCENTAGE`. Use `OTHER` with `customUnitOfMeasurement` for any other unit.
`granularity`	The time scale: `SECOND`, `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`, `QUARTER`, or `YEAR`.
`relatedMetrics`	Fully qualified names of other metrics that this metric relates to. Each related metric must already exist.
`owners`	References to users or teams, each with the `id` and `type`. A team owner must be a Group team.
`reviewers`	References to one or more users, or to a single team, each with the `id` and `type`.

For all fields, see Create a Metric.

Metric vs. Glossary Term

A metric and a glossary term can describe the same business idea, but they do different jobs:

	Metric	Glossary Term
Describes	A measurement, such as Customer Retention Rate	A business concept, such as Customer
Holds	An expression, a metric type, a unit, a granularity, and related metrics	A definition, synonyms, related terms, and a review workflow
Use it to	Record how a number is calculated, so everyone uses the same definition	Give teams a shared vocabulary, and tag data assets with it

Use a glossary term to define what a “customer” is. Use a metric to define how you count retained customers.

KPIs and metrics are separate. A KPI can’t be linked to a metric. For more information, see Key Performance Indicators (KPIs).

Managing Metrics in Collate

Versioning: Each update to a metric creates a new version, maintaining historical changes.
Linking: Metrics can be linked to glossary terms, tables, dashboards, and pipelines for enriched context.
Monitoring: Collate stores the metric’s definition. Collate AI can run a saved metric’s SQL on demand; for continuous tracking, monitor the values in your own database or BI tool.

Best Practices for Metric Management

Consistent Naming: Use camelCase for metric names to ensure consistency across systems.
Clear Definitions: Provide comprehensive descriptions and units for accurate interpretation.
Lineage Tracking: Always associate metrics with source tables and pipelines for traceability.
Ownership: Assign metric owners for accountability and maintenance.

​Metrics in Collate

​Overview of Metrics

​What a Metric Stores

​Calculation and Scheduling

​Key Properties of a Metric

​Metric Lineage and Dependencies

​Creating Metrics Using the UI

​Example JSON for Creating a Metric

​Metric vs. Glossary Term

​Managing Metrics in Collate

​Best Practices for Metric Management

Metrics in Collate

Overview of Metrics

What a Metric Stores

Calculation and Scheduling

Key Properties of a Metric

Metric Lineage and Dependencies

Creating Metrics Using the UI

Example JSON for Creating a Metric

Metric vs. Glossary Term

Managing Metrics in Collate

Best Practices for Metric Management