Skip to main content
Preview 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. 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. 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: 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. 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

  • 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.
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.
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. 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.