Certified queries

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, alongside your cubes and views.

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.

<!-- 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:

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

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. In a multi-agent setup, 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.

Connect to data

Users & Permissions

SSO & Identity Providers

Deployment

Monitoring

AI

Account

Defining certified queries

Frontmatter properties

Inlining certified queries in YAML

Writing effective certified queries

​Defining certified queries

​Frontmatter properties

​Inlining certified queries in YAML

​Writing effective certified queries

Defining certified queries

Frontmatter properties

Inlining certified queries in YAML

Writing effective certified queries