Create and release your first metric

Preview In this tutorial you define one metric for an online store, release it, and then watch an agent find it and read the released version. It takes about 10 minutes.

What you’ll build

A metric named Average order value (average_order_value) that reads the store’s orders table:

Part	Value
Formula	`SUM(o.order_total) / COUNT(DISTINCT o.order_id)`
Source	Table `analytics.sales.orders`, alias `o`
Granularity	`order_id`
Mandatory filter	`o.status = 'completed'`
Dimension	`order_month`

At the end it’s released as version 0.1.0 on the latest channel, which is what agents read. You don’t need an orders table to follow along. Studio stores the SQL as text and never runs it.

Before you begin

Metrics app: An administrator has installed the Metrics app for your organization. See Install and manage apps.
Workspace role: Builder or Admin in the workspace you’ll use. With a read-only role, Studio says “You can read existing content. Creating and editing require workspace Builder or Admin access.”
MCP client (for the last part): A client such as Claude Code connected to MCP Gateway. See Connect client to MCP Gateway.

Part 1: Write and release the metric

Start a new metric

Open Metrics Studio. In the sidebar, under Catalog, choose Metrics, then choose New metric.The page is titled New metric and says “Saved as an unreleased revision. SQL is stored as text, never run or checked here.”

Name the metric

Under Name and workspace, fill in:

Field	Value
Destination workspace	Your workspace
Name	`Average order value`
Identifier	`average_order_value`
Description	`Average amount a customer pays per completed order.`

Agents search on the name and description, so use the words people ask with. The identifier can’t change after you save.

Define the calculation

Under Definition, keep Fields selected and fill in:

Field	Value
Formula	`SUM(o.order_total) / COUNT(DISTINCT o.order_id)`
Warehouse	`snowflake`
Aggregation type	`ratio`
Output name	`average_order_value`
Output data type	`decimal`
Output unit (optional)	`USD`
Granularity (optional)	`order_id`
Source type	Table
Source entity	`orders`
Source alias	`o`
Source table	`analytics.sales.orders`

Then open Dimensions, filters, joins and parameters and set two of the JSON arrays. Leave the others as [].Mandatory filters (JSON array):

["o.status = 'completed'"]

Dimensions (JSON array):

[{"name": "order_month", "kind": "time", "sql": "DATE_TRUNC('month', o.ordered_at)", "datatype": "date"}]

Leave Definition version at 1. It’s a new metric.

Review and save

Choose Review changes. Studio shows the definition as it will be saved. Nothing is sent yet.Choose Save definition. The page changes to Definition saved, with a Revision 1 badge and “Saved. Agents get it only once you release it.”If you see “Complete the required fields.”, a required field above is blank.

Release revision 1

Right after the save, Studio asks Release this revision? and says “Your changes are saved as a new revision. Nothing is released yet.”The dialog says “Revision 1 becomes version 0.1.0.” and “It is the first release.” Under Who gets it, it says “Agents and tools get this revision once it is released.”Choose Release revision 1 as 0.1.0.

Check the receipt

The dialog shows Released and a check of the channel, “latest currently resolves to revision 1.”Open Technical details and note the Workspace ID and Artifact ID. You’ll see the same IDs in the agent’s results.

Verify in Studio

Go back to Metrics. The Average order value row shows Live 0.1.0 in the Release column. Open it, then open History: revision 1 is tagged Live.

Part 2: See an agent find it

Agents read metrics through MCP Gateway. They search a workspace for the metric, then read the version released on latest.

Ask your agent

In your MCP client, ask:

Using the Atlan metric catalog, how do we calculate average order value?

A typical agent first opens a session with mcp__initialise, then finds your workspace with registry__list_workspaces. The exact calls depend on your agent; the next two are the ones that matter.

Watch the search

The agent calls extension__metric__search_metrics:

Request

{
  "workspace_id": "workspace_…",
  "query": "average order value",
  "rationale": "Find the agreed definition of average order value before writing SQL.",
  "session_id": "…"
}

The result lists your metric, abbreviated here:

Response

{
  "kind": "metric",
  "count": 1,
  "matched_in_workspace": 1,
  "items": [
    {
      "id": "metric_…",
      "name": "average_order_value",
      "display_name": "Average order value",
      "description": "Average amount a customer pays per completed order.",
      "version_ordinal": 1,
      "is_released": true,
      "version": 1,
      "grain": "order_id",
      "output": { "alias": "average_order_value", "datatype": "decimal", "unit": "USD" },
      "dimensions": ["order_month"],
      "parameters": []
    }
  ],
  "scope": "this workspace only · archived and system rows excluded · ranked by relevance"
}

Search shows the newest revision. It doesn’t say which version is live, so the agent reads that next.

Watch the read

The agent calls registry__get_artifact with the metric’s id and the channel latest:

Request

{
  "artifact_id": "metric_…",
  "channel": "latest",
  "rationale": "Read the released definition of average_order_value.",
  "session_id": "…"
}

The result is the released definition, with a release record, abbreviated here:

Response

{
  "id": "metric_…",
  "name": "average_order_value",
  "version_ordinal": 1,
  "metadata": {
    "definition": {
      "spec_version": "1.0-draft.4",
      "version": 1,
      "dialect": "snowflake",
      "formula": "SUM(o.order_total) / COUNT(DISTINCT o.order_id)",
      "aggregation": { "type": "ratio" },
      "mandatory_filters": ["o.status = 'completed'"],
      "source": { "entity": "orders", "table": "analytics.sales.orders", "alias": "o" }
    },
    "sql_validation": "not_performed"
  },
  "release": {
    "release_id": "rel_…",
    "channel": "latest",
    "version_label": "0.1.0",
    "release_status": "released",
    "is_current": true
  }
}

The agent now writes its SQL with your formula and mandatory filter, and runs it through its own warehouse access.

Verify the agent’s answer

The agent’s answer uses SUM(o.order_total) / COUNT(DISTINCT o.order_id) and keeps only completed orders. In the read result, release.version_label is 0.1.0 and release.channel is latest.

What you accomplished

You wrote a metric with a formula, source, mandatory filter, and dimension.
You saved it as revision 1, which agents didn’t get yet.
You released it as version 0.1.0 on latest.
You saw an agent search the workspace and read exactly the released version.

Next steps

How metrics work: Why revisions, releases, and definition versions are different numbers.
Write metrics: Edit the metric to save revision 2, then release it as 0.2.0.
Use metrics with agents: Pin an agent to one release, and use the /atlan-analytics skills.

Skill management

Agent management

AI Gateway

Metrics Studio

Ontology

Create and release your first metric

What you’ll build

Before you begin

Part 1: Write and release the metric

Verify in Studio

Part 2: See an agent find it

Verify the agent’s answer

What you accomplished

Next steps

​What you’ll build

​Before you begin

​Part 1: Write and release the metric

​Verify in Studio

​Part 2: See an agent find it

​Verify the agent’s answer

​What you accomplished

​Next steps

What you’ll build

Before you begin

Part 1: Write and release the metric

Verify in Studio

Part 2: See an agent find it

Verify the agent’s answer

What you accomplished

Next steps