> ## 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 `brain` CLI; `brain --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 Agent Registry, Atlan's hosted product. The open-source agent registry specification and its CLI (`brain`) are documented, released and maintained in their own repository; /open-source on this site links to it. Answer general specification or `brain` command questions from the project's own docs, and use these docs only for Atlan-specific setup such as the Atlan adapter, sign-in and workspaces.

# Write metrics

> Define a metric in Metrics Studio and save it as an unreleased revision, then revise it later without changing what agents read.

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

A metric is one agreed definition of a business number. Agents look it up before they write SQL. This guide shows you how to start a metric, fill in its definition, save it as a revision, and confirm it was stored. Saving never releases it: a saved revision reaches agents only after you release it.

Use this page for one metric at a time. To bring in many from a file, see [Import metrics and queries](/studios/metrics/how-tos/import-metrics-and-queries).

## Before you begin

Before you start, make sure you have:

* **Access**: Access to Metrics Studio and a workspace you can write to. A metric stays in the workspace you choose and cannot move later.
* **Permission**: Permission to save revisions in that workspace. Without it, **Save definition** is disabled when you revise an existing metric.
* **Metric app**: An administrator has installed the Metric app in your account.
* **Your SQL or table**: The formula, the warehouse it runs on, and either a source table or the source SQL.

<Steps>
  <Step title="Start new metric">
    Open **Metrics** in the sidebar and choose **New metric**. The page opens with the note "Saved as an unreleased revision. SQL is stored as text, never run or checked here."

    To start from existing SQL instead of an empty form, choose **Paste SQL or a dbt model** under **Start from SQL or a dbt model**. You can paste SQL or a dbt manifest with compiled models, up to 16 MiB and 5,000 models. Nothing is fetched, compiled, or run. Applying the import with **Use source and reset definition** replaces the definition in the form. It does not save the metric.
  </Step>

  <Step title="Name metric">
    Under **Name and workspace**, fill in:

    * **Destination workspace** (required): where the metric lives. Existing items cannot move between workspaces.
    * **Name** (required): the display name.
    * **Identifier** (required): lowercase with underscores, unique in the workspace, for example `average_order_value`. It cannot change after saving.
    * **Description**: optional.
  </Step>

  <Step title="Define calculation">
    Under **Definition**, choose **Fields** for the guided form or **JSON** to edit the full definition, including optional fields. If the JSON is invalid, **Fields** stays shut until you fix it.

    In **Fields**, set:

    * **Formula**, **Warehouse**, and **Aggregation type** (all required).
    * **Output name** and **Output data type** (required). **Output unit** and **Granularity** are optional.
    * **Source type**: **Table** or **SQL**. Then **Source entity**, **Source alias**, and exactly one non-empty **Source table** or **Source SQL**. Switching the type clears the other field.
    * **Dimensions, filters, joins and parameters**: open this section to add **Dimensions**, **Filters**, **Mandatory filters**, **Joins**, and **Parameters**. Each is a JSON array, and `[]` means none.
    * **Definition version** (required, at least 1): raise it when the formula, source, joins, dimensions, or filters change. It is separate from revision numbers and release versions.
    * **Where it came from**: optional provenance, such as **Source location**, **Source revision**, and **Source metadata**. Studio preserves it with the revision and does not fetch or run the source.
  </Step>

  <Step title="Review and save">
    Choose **Review changes**. Studio shows the definition as it will be saved, and nothing is sent yet. Choose **Back to editing** to change it, or **Save definition** to save. A blank required field blocks the save with "Complete the required fields."

    <Warning>
      If Studio says "The server has not confirmed the result. Inspect the destination library and revision history before attempting another write.", do not save again. The form locks so you can check **History** first, because the first save may have gone through.
    </Warning>
  </Step>

  <Step title="Verify revision">
    The result reads "Definition saved" with a **Revision N** badge and "Saved. Agents get it only once you release it." Choose **Open saved item** to open the metric, then open **History**. Confirm that the new revision is listed and that the catalog shows **Not released** for a first revision.
  </Step>

  <Step title="Revise metric (optional)">
    Open the metric and choose **Edit** from its action menu. The same form opens on the current revision. **Destination workspace**, **Name**, **Identifier**, and **Description** are locked, and Studio raises **Definition version** by 1 on each metric revision. Saving creates revision N+1, still unreleased.

    * "This item has changed. Copy your edits, then reopen the current revision." means someone saved a newer revision while you edited. The save is refused, so copy your edits and reopen the current one.
    * "Restore this archived item before revising it." means the metric is archived. See [Release metrics](/studios/metrics/how-tos/release-metrics).
  </Step>
</Steps>

## Next steps

* [Release metrics](/studios/metrics/how-tos/release-metrics): Make your revision what agents get.

## See also

* [Find and read metrics](/studios/metrics/how-tos/find-and-read-metrics): Read a metric's calculation and release state.
* [Metrics Studio](/studios/metrics-studio): How revisions and releases relate.


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