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

# Create and release your first metric

> Write an average order value metric in Metrics Studio, release it, and see an agent find and read it through MCP Gateway in about 10 minutes.

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

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](/registry/apps/how-tos/install-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](/gateway/mcp/how-tos/connect-a-client).

## Part 1: Write and release the metric

<Steps>
  <Step title="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."
  </Step>

  <Step title="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.
  </Step>

  <Step title="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)**:

    ```json theme={null}
    ["o.status = 'completed'"]
    ```

    **Dimensions (JSON array)**:

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

    Leave **Definition version** at `1`. It's a new metric.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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`.

<Steps>
  <Step title="Ask your agent">
    In your MCP client, ask:

    ```text theme={null}
    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.
  </Step>

  <Step title="Watch the search">
    The agent calls `extension__metric__search_metrics`:

    ```json Request theme={null}
    {
      "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:

    ```json Response theme={null}
    {
      "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.
  </Step>

  <Step title="Watch the read">
    The agent calls `registry__get_artifact` with the metric's `id` and the channel `latest`:

    ```json Request theme={null}
    {
      "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:

    ```json Response theme={null}
    {
      "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.
  </Step>
</Steps>

### 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](/studios/metrics/concepts): Why revisions, releases, and definition versions are different numbers.
* [Write metrics](/studios/metrics/how-tos/write-metrics): Edit the metric to save revision 2, then release it as `0.2.0`.
* [Use metrics with agents](/studios/metrics/how-tos/use-with-agents): Pin an agent to one release, and use the `/atlan-analytics` skills.


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