> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `aireg` CLI; `aireg --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
> These docs cover Atlan AI Registry, Atlan's hosted product. The AI registry specification and aireg CLI are maintained separately. /open-source lists publicly reachable signed installers and explains that the source repository and hosted CLI reference currently require GitHub access. Do not claim the repository or its reference docs are publicly accessible. Use these docs for Atlan-specific setup such as the adapter, sign-in and workspaces.

# How metrics work

> What a metric and a saved query hold, how revisions, releases, and definition versions differ, and how metrics link to each other.

<Badge color="orange">Preview</Badge>

A **metric** is one agreed definition of a business number: how to calculate it, from which data, and how it can be broken down. Metrics Studio stores that definition as text, and agents read it before they write SQL. Nothing in Studio runs the SQL.

This page uses one example throughout: an online store with an `orders` table, and the metrics `revenue` and `average_order_value`.

## Metrics and saved queries

Studio holds two kinds of item. Both live in one workspace and keep every saved revision.

| | Metric | Saved query |
| - | - | - |
| What it is | The agreed calculation of one number, such as `average_order_value` | One piece of trusted SQL and the question it answers, such as "What was revenue by month last year?" |
| What it holds | Formula, aggregation, output, source, joins, dimensions, filters, parameters | SQL, question, other phrasings, warehouse, usage note, extracted tables and columns |
| Released to agents? | Yes. Agents read the version released on a channel. | No. Agents read its newest revision. |
| How agents find it | `extension__metric__search_metrics` | `extension__metric__search_queries` |
| Typical use | The number everyone must calculate the same way | A proven query an agent can reuse or adapt |

A useful saved query can become a metric. On the query's page, **Create a metric from this query** copies its SQL and warehouse into a new, unreleased metric, and links the two.

## Parts of a metric

Studio's form and the stored definition sometimes use different words for the same thing. The MCP tools return the stored field names.

| Part | Stored field | In Studio | Example (`average_order_value`) |
| - | - | - | - |
| Formula | `formula` | **Formula** | `SUM(o.order_total) / COUNT(DISTINCT o.order_id)` |
| Warehouse | `dialect` | **Warehouse** | `snowflake` |
| Aggregation | `aggregation.type` | **Aggregation type** | `ratio` |
| Output | `output.alias`, `output.datatype`, `output.unit` | **Output name**, **Output data type**, **Output unit** | `average_order_value`, `decimal`, `USD` |
| Source | `source.entity`, `source.alias`, and `source.table` or `source.sql` | **Source entity**, **Source alias**, **Source table** or **Source SQL** | `orders`, `o`, `analytics.sales.orders` |
| Joins | `joins` | **Joins** | `customers` on `o.customer_id = c.customer_id` |
| Dimensions | `dimensions` | **Dimensions** | `order_month`, `customer_region` |
| Filters | `filters` | **Filters** | `o.order_total > 0` |
| Mandatory filters | `mandatory_filters` | **Mandatory filters** | `o.status = 'completed'` |
| Parameters | `source.parameters` | **Parameters** | `start_date` |
| Granularity | `grain` | **Granularity** | `order_id` |
| What it includes | `population` | **Includes** (on **Overview**) | Completed orders from the online store |
| What it excludes | `exclusions` | **Excludes** (on **Overview**) | Test orders |

What each part means:

* **Formula** is the expression that computes the number. It's stored exactly as written.
* **Aggregation** says how the formula combines rows: `sum`, `count`, `count_distinct`, `min`, `max`, `ratio`, or `custom`. A value outside this list is kept, with a warning. You can also record how the number rolls up across groups and how it treats missing values.
* **Output** names the result column and its data type, with an optional unit.
* **Source** is the table or SQL the metric reads, with an alias the formula uses. A metric has exactly one: a table or SQL, never both.
* **Joins** add other tables, each with its join SQL and cardinality, such as `many_to_one`. Studio doesn't infer joins.
* **Dimensions** are the ways the number can be broken down, such as by month or by region. A dimension that needs a join names it.
* **Filters** and **mandatory filters** are SQL conditions. Studio lists both as conditions the metric applies and marks the mandatory ones. Use a mandatory filter for a condition that must never be dropped, such as excluding cancelled orders.
* **Parameters** are values a caller supplies each time, with a data type and a default. A mandatory filter can refer to a parameter as `:name`, for example `o.ordered_at >= :start_date`.

### Grain, granularity, and population

These three terms describe *which rows* the number is about. They overlap, so here is how they map:

| Term | Where you see it | What it means |
| - | - | - |
| `grain` | Stored field, and the `grain` field in search results | The row level the metric works at, for example `order_id` |
| **Granularity** | Studio's form and **Overview** | The same field as `grain`. Studio uses the plainer word. |
| `population` | Stored field, and the `population` field in search results | In words, which rows the number covers, for example "Completed orders from the online store" |
| **Includes** | **Overview** in Studio | The same field as `population` |
| `exclusions` / **Excludes** | Stored field / **Overview** | Rows the number leaves out, for example "Test orders" |

On **Overview**, hover a label to see its stored field name. The guided form has a **Granularity** field. To set `population` or `exclusions`, switch **Definition** to **JSON**.

## Three different version numbers

A metric carries three numbers, and each answers a different question.

| Number | Example | Who sets it | When it changes | Where you see it |
| - | - | - | - | - |
| **Definition version** (`version`) | `2` | You, in the definition | You raise it when the calculation changes | **Definition version** in the editor; `version` in search results |
| **Revision** (`version_ordinal`) | Revision 5 | Atlan | Every save adds one | **Revision 5** badge and **History** |
| **Release version** (`version_label`) | `0.2.0` | Atlan, when you release | Each release on `latest` gets the next minor number | **Live 0.2.0** in the catalog; **Version 0.2.0** page |

Rules for the definition version:

* It must be a whole number of 1 or more.
* When the calculation changes, it must go up. The calculation covers the formula, warehouse, aggregation, output, source, joins, dimension SQL, filters, mandatory filters, dependencies, granularity, population, and exclusions.
* When only wording, examples, or where-it-came-from details change, it can stay the same.
* It can never go down. Studio raises it by 1 each time you edit a metric.

The definition also has a format version, `spec_version`. New metrics use `1.0-draft.4` and new saved queries use `1.0-draft.1`.

## Lifecycle

```mermaid theme={null}
stateDiagram-v2
  [*] --> Saved: Save (Revision 1)
  Saved --> Saved: Save again (Revision 2, 3…)
  Saved --> Live: Release on latest (Version 0.1.0)
  Live --> Live: Release a newer revision (0.2.0 replaces 0.1.0)
  Live --> Saved: Withdraw (previous version is live again, or nothing)
  Saved --> Archived: Archive
  Live --> Archived: Archive (its releases are retired)
  Archived --> Saved: Restore as a new revision
```

* **Save** creates a revision. Saving in Studio never releases, so agents keep getting the live version.
* **Release** distributes one revision on a channel, `latest` by default. Agents that read the channel get it. The version it replaces stays readable by its number.
* **Withdraw** takes one release back for good. The channel then serves the previous version whose revision is still active, or nothing. Agents that search still find the metric.
* **Replace** names a successor in a new revision. It releases nothing and withdraws nothing. Agents still get the old metric until you archive it.
* **Archive** retires the metric's releases and removes it from the list and search. Its history stays, and **Restore as a new revision** brings it back unreleased.

Saved queries have no releases. Saving one changes what agents find right away.

<Note>
  Studio always saves with release off. A write through the Atlan API follows the workspace's release policy instead, so it can ship straight away. See [Set workspace release policy](/administer/workspaces/how-tos/set-release-policy).
</Note>

## Links between metrics and queries

Atlan records four kinds of link. Studio shows them on a metric's **Dependencies** tab and in the release dialog. Agents read them with `registry__get_related_artifacts`.

| Link | From → to | How it's created | Example |
| - | - | - | - |
| `depends_on` | Metric → metric | Atlan adds it when the definition's `depends_on` names a live metric in the same workspace | `average_order_value` depends on `revenue` |
| `replaced_by` | Metric → metric | Atlan adds it when the definition's `replaced_by` names a live metric. **Name a replacement** sets it. | `aov_legacy` is replaced by `average_order_value` |
| `uses_metric` | Saved query → metric | On the query, **Link a metric** with **This query uses the metric** | "Revenue by region" uses `revenue` |
| `source_of` | Saved query → metric | **Create a metric from this query**, or **Link a metric** with **The metric was created from this query** | "Average basket size" is the source of `average_order_value` |

A name that matches no live metric gets no link, but the definition keeps the name. The link appears the next time the dependent metric is saved after the target exists.

A metric keeps its own copy of the SQL it's built from. Releasing `revenue` doesn't change the numbers of a metric built from it. Studio lists only recorded links, so an empty list doesn't prove that nothing uses a metric.

## Related

* [Metric definition fields](/studios/metrics/references/definition-fields): Every field, its type, and its limits.
* [Write metrics](/studios/metrics/how-tos/write-metrics): Fill in these parts in Studio.
* [Release metrics](/studios/metrics/how-tos/release-metrics): Turn a revision into the version agents get.
* [Use metrics with agents](/studios/metrics/how-tos/use-with-agents): How agents search and read metrics.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.