> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cube.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Certified queries

> Provide a library of trusted SQL queries that the agent uses as reference examples when answering user requests.

Certified queries are pre-approved SQL queries that the agent treats as a **library of trusted examples**. They guide the agent toward correct business logic and well-formed query patterns without restricting it to a fixed set of queries.

Certified queries are configured as code in your [data model repository](https://docs.cube.dev/admin/ai.md#agent-configuration), alongside your cubes and views.

> [!NOTE]
>
> The agent is not limited to running only certified queries. When answering a user request, the agent may:
>
> * Use a certified query directly if it matches the request
> * Use a certified query as a **starting point** and adapt it (e.g., add filters, dimensions, or measures) to fit the user's question
> * Generate a new query independently if no certified query is relevant
>
> Certified queries help the agent toward trusted patterns and correct business logic, but the agent retains full flexibility to construct the query that best answers each question.

## Defining certified queries

Certified queries are defined as Markdown files under `agents/certified_queries/`. Each query lives in its own file: the YAML frontmatter holds metadata, and the Markdown body is the SQL query.

```markdown theme={"dark"}
<!-- agents/certified_queries/quarterly-revenue.md -->
---
description: "Get revenue by fiscal quarter"
user_request: "What is the revenue by quarter?"
---
SELECT
  DATE_TRUNC('quarter', order_date) AS quarter,
  SUM(amount) AS revenue
FROM orders
WHERE status != 'cancelled'
GROUP BY 1
ORDER BY 1
```

Files placed under a `certified_queries/`, `certified-queries/`, or `queries/` directory are treated as certified queries automatically — no `kind` property is required. The `name` is inferred from the file name (e.g., `quarterly-revenue.md` → `quarterly-revenue`).

### Frontmatter properties

| Property | Type | Required | Description |
| - | - | :-: | - |
| `name` | string | No | Unique identifier. Inferred from the file name if omitted. |
| `description` | string | No | Human-readable description. |
| `user_request` | string | Yes | The user request pattern this query answers. |
| `sql_query` | string | No | The SQL query. Falls back to the Markdown body if omitted. |

### Inlining certified queries in YAML

You can also inline certified queries directly in `agents/config.yml` under a `certified_queries` key:

```yaml theme={"dark"}
# agents/config.yml
certified_queries:
  - name: total-revenue
    description: "Calculate total revenue"
    user_request: "What is the total revenue?"
    sql_query: "SELECT SUM(amount) AS total_revenue FROM orders WHERE status = 'completed'"

  - name: monthly-sales
    description: "Monthly sales breakdown"
    user_request: "Show me sales by month"
    sql_query: |
      SELECT
        DATE_TRUNC('month', order_date) AS month,
        SUM(amount) AS total_sales
      FROM orders
      GROUP BY 1
      ORDER BY 1
```

Inline certified queries accept the same properties as Markdown ones — `name`, `description`, `user_request` (required), and `sql_query` (required).

> [!NOTE]
>
> Certified queries inlined at the root of `agents/config.yml` are attached to the implicit `auto` space and applied to the default agent in a [single-agent setup](https://docs.cube.dev/admin/ai.md). In a [multi-agent setup](https://docs.cube.dev/admin/ai/multi-agent.md), attach certified queries to a specific space by inlining them under that space's `certified_queries` key (or by placing Markdown files under `agents/certified_queries/<space-name>/`).

## Writing effective certified queries

* **Phrase `user_request` like a real user question.** This is what the agent matches against incoming requests.
* **Keep queries focused.** A certified query should answer one well-defined question; the agent will adapt it for variations.
* **Use canonical business logic.** Certified queries are the reference for "the right way" to compute something — encode the definitions you want the agent to follow.
* **Cover common patterns first.** Start with the questions users ask most often, and grow the library based on usage.


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