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

# Save queries

> Save trusted SQL with the question it answers in Metrics Studio so agents can find it, and edit it later as a new revision.

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

A saved query is trusted SQL plus the question it answers. Agents retrieve it at run time, and a useful one can become a metric. SQL is stored as text and never run in Studio. This guide shows you how to browse saved queries, save a new one, edit it, and confirm it was stored.

## 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.
* **Your SQL**: The query text, the warehouse it targets, and the business question it answers.

<Steps>
  <Step title="Open saved queries">
    In the sidebar, under **Catalog**, choose **Saved queries**. The list has the columns **Question**, **Ran when saved**, **Tables**, **Runs**, **Users**, and **Last run**. A row with no title shows "No question yet".

    Search with **Question, table or column**, which matches the question, name, description, tables, and columns. Use the views **All**, **No question**, **No usage note**, and **Archived**, and the filters **Table**, **Warehouse**, **Ran when saved**, and **Last run**. Sort by **Most run** (the default), **Most users**, **Last run**, or **Recently updated**.

    Runs, users, and whether the SQL ran are as recorded by whoever saved each query. **Ran when saved** shows **Yes**, **Not run**, or **Rejected**.
  </Step>

  <Step title="Start new query">
    Choose **New query**. The page is titled "New saved query" and carries the same note as a metric: "Saved as an unreleased revision. SQL is stored as text, never run or checked here." It begins with the same **Name and workspace** section as a metric, so choose the destination workspace and give the query a name and an identifier.
  </Step>

  <Step title="Fill in query">
    Complete:

    * **Question**: the business question the SQL answers.
    * **SQL text** (required): the query. A blank value blocks the save with "Complete the required fields."
    * **Warehouse**: the dialect it targets.
    * **Usage notes**: how and when to use it.
  </Step>

  <Step title="Review and save">
    Choose **Review changes**, then **Save definition**. Nothing is sent until you choose **Save definition**.

    <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. Check the list and the query's history first.
    </Warning>
  </Step>

  <Step title="Verify query">
    The result reads "Definition saved" with a **Revision N** badge. Choose **Open saved query**, then return to **Saved queries** and confirm the row appears with the question you entered.
  </Step>

  <Step title="Edit query (optional)">
    Open the query and choose **Edit**. Editing opens the current revision, and earlier revisions are read-only. Saving creates a new revision. If you change the SQL or the warehouse, **Ran when saved** goes back to **Not run**.
  </Step>
</Steps>

## Next steps

* [Import metrics and queries](/studios/metrics/how-tos/import-metrics-and-queries): Bring in many queries or query history at once.
* [Write metrics](/studios/metrics/how-tos/write-metrics): Turn a trusted query into a metric.

## See also

* [Metrics Studio](/studios/metrics-studio): How saving and releasing differ.
* [MCP tool catalog](/tools/mcp/references/tool-catalog): The tool agents use to search saved queries.


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