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

# Import metrics and queries

> Preview and import many metrics, saved queries, or query history into Metrics Studio from a file, and resolve duplicates before anything is saved.

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

Importing lets you bring many definitions into Metrics Studio at once instead of writing each by hand. Use it when you already have metric definitions, saved queries, or query history in files. Studio previews every row first, and nothing is run or fetched. This guide shows you how to load a file, preview and fix rows, import the ones you choose, and read the report.

## Before you begin

Before you start, make sure you have:

* **Access**: Access to Metrics Studio and a workspace you can write to.
* **Metric app**: An administrator has installed the Metric app in your account.
* **A file or pasted content**: JSON for metrics (an array of envelopes, each with `name`, `display_name`, and `definition`, or an object with an `items` array). For queries, JSON records or a CSV of execution history. A file is limited to 1 MiB.

<Steps>
  <Step title="Open import page">
    - **Metrics**: in the sidebar, under **Build**, choose **Import**, or choose **Import metrics** on the catalog. The page says "Import up to 100 metrics."
    - **Saved queries**: choose **Import queries** on **Saved queries**. Import up to 1,000 records at a time.
  </Step>

  <Step title="Choose destination">
    Pick the **Destination workspace**. For queries, also set **Source format**: **Saved query records (JSON)** or **Execution history (CSV)**. History needs a **History source or source location**, for example `example://query-history`. It identifies where execution IDs came from so the same ID from two systems is not confused. Studio does not fetch it.
  </Step>

  <Step title="Add content">
    Choose a file, or paste into **Import content**. Loading a file replaces what is in the box. Choosing a file larger than 1 MiB shows an error, and each Registry request must fit within 4 MiB.

    <Tabs>
      <Tab title="Metrics (JSON)">
        An array of envelopes with `name`, `display_name`, and `definition`, or an object with an `items` array. Source location, revision, and metadata are optional.
      </Tab>

      <Tab title="Saved query records (JSON)">
        An array of `{name, display_name, definition}` records, or `{items: [...]}`. Each definition needs `spec_version` set to `"1.0-draft.1"` and `sql`. Optional `source_uri`, `source_version`, and `source_metadata` are preserved.
      </Tab>

      <Tab title="Execution history (CSV)">
        Columns `execution_id`, `executed_at` (with a time zone, such as `2026-01-01T00:00:00Z`), and `sql` are required. Optional columns are `name`, `question`, `dialect`, `user_id`, and `usage_note`. Quoted multiline SQL is supported, and each execution ID must identify one consistent record in the source.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Preview and fix rows">
    Choose **Preview mappings and duplicates**. Studio checks every row and labels it. For metrics: **Ready**, **Needs correction**, **Name already used**, **Saved**, **Failed**, or **Outcome unknown**. Name checks include archived metrics. For queries: **Ready**, **Needs correction**, **Existing match**, **Saved**, **Failed**, **Unconfirmed**, or **Skipped**.

    * To fix a row, choose **Edit row**, change its JSON, and choose **Apply and recheck row**.
    * A name repeated inside the file is blocked. Choose a distinct name.
    * For a metric whose name exists, choose **Find this name in the metric library** or **Find archived metrics with this name**.
    * For a query with an **Existing match**, you can choose **Attach history evidence** to add history to the match in a new revision (the SQL and dialect must be the same, and executions already imported are skipped), or **Create a separate query with this SQL**. A name that already exists cannot be overridden.

    Grouping compares SQL text, dialect, and parameters. It does not verify meaning.
  </Step>

  <Step title="Import chosen rows">
    For metrics, tick **I reviewed the destination and selected metric definitions.** The final button stays disabled until you do and at least one row is selected. Then choose **Import {N} selected rows** (queries: **Import selected ({N})**).

    <Warning>
      Saved rows and rows with an unknown outcome cannot be replayed. If Studio says "The request may have completed. This row is locked against retry.", inspect the destination before you do anything else. An unknown outcome stops the batch until you choose to continue.
    </Warning>

    Rows that failed definitively can be corrected and imported again.
  </Step>

  <Step title="Verify import">
    Open **Import report** to see each row's result, and choose **Copy import report** to keep it. Studio holds the report only on this page, so copy it before you leave. Saved rows link to the saved item with its revision. Then open the catalog or **Saved queries** and confirm the items are there. Check each item's release state, because releasing is a separate step.
  </Step>
</Steps>

## Next steps

* [Release metrics](/studios/metrics/how-tos/release-metrics): Make an imported metric what agents get.

## See also

* [Write metrics](/studios/metrics/how-tos/write-metrics): Define one metric by hand.
* [Save queries](/studios/metrics/how-tos/save-queries): Save one query by hand.


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