Skip to main content
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

PropertyTypeRequiredDescription
namestringNoUnique identifier. Inferred from the file name if omitted.
descriptionstringNoHuman-readable description.
user_requeststringYesThe user request pattern this query answers.
sql_querystringNoThe 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).

​
Comments and agent visibility

When the agent searches for a matching certified query, it only considers the description and user_request fields. Comments are never used for matching, but Markdown comments are included in the query content the agent reads once a query has been selected — so they can provide additional information about the query (context, caveats, or hints) that influences how the agent uses it.
  • Markdown comments (<!-- ... -->) in the body of the file are included in the content the agent reads. Use them to add extra context, caveats, or hints about the query once it’s selected.
  • YAML comments (# ...) in the frontmatter are not included in the content the agent reads. Use them for internal notes, authorship, or review metadata that should stay hidden from the agent.
<!-- agents/certified_queries/quarterly-revenue.md -->
---
# Internal note: reviewed by the analytics team on 2025-01-15 — hidden from the agent
description: "Get revenue by fiscal quarter"
user_request: "What is the revenue by quarter?"
---
<!-- Exclude cancelled orders; finance considers these non-revenue. -->
SELECT
  DATE_TRUNC('quarter', order_date) AS quarter,
  SUM(amount) AS revenue
FROM orders
WHERE status != 'cancelled'
GROUP BY 1
ORDER BY 1
To make a query discoverable by the agent, put matching signals in description and user_request — those are the only fields used for search. Use Markdown comments for additional context the agent should consider when using the query, and keep YAML comments for notes aimed at other developers.

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