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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/modeling/models/sample-queries",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# sample_queries

> Defines a list of sample queries that could be performed using the topics in the model.

Defines a list of sample queries that could be performed using the topics in the model, which is used:

* **To present example queries** when a model is selected in the workbook or using the [embedded version of the Omni Agent](/embed/customization/ai-chat).

  To hide the query, set the `hidden` parameter to `true`.

* [**By the Omni Agent to improve results.**](/ai/chat) To exclude the query from the model's AI context, set the `exclude_from_ai_context` to `true`.

You can also add [sample queries to individual topics](/modeling/topics/parameters/sample-queries).

## Syntax

```yaml theme={null}
sample_queries:
  <query_name>:
    query:
      fields: [ "<field_one>", "<field_two>", ... ]
      base_view: "<base_view_name>"
      calculations:
        <calculation_name>:
          sql: "<sql_expression>"
      limit: <number>
      sorts:
        - field: "<field_name>"
          desc: true/false
      topic: "<topic_name>"
    description: "<query_description>"
    hidden: true/false
    prompt: "<natural_language_prompt>"
    ai_context: "<ai_context_description>"
    exclude_from_ai_context: true/false
```

## Properties

<ParamField path="query_name" type="object" required>
  The name of the sample query (e.g., "Summary Stats"). Each query is defined as a key in the `sample_queries` object.

  <Expandable title="query properties" defaultOpen="true">
    <ParamField path="query" type="object" required>
      The query definition object containing the structure of the query to be executed.

      <Expandable title="query properties" defaultOpen="true">
        <ParamField path="fields" type="string[]" required>
          List of fields to include in the query. Can reference model fields or calculations.
        </ParamField>

        <ParamField path="base_view" type="string" required>
          The base view or topic to query from.
        </ParamField>

        <ParamField path="calculations" type="object">
          Optional calculations to include in the query. Each calculation is defined with a name and SQL expression.

          <Expandable title="calculation properties" defaultOpen="true">
            <ParamField path="sql" type="string" required>
              The SQL expression for the calculation.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField path="limit" type="number">
          Maximum number of rows to return.
        </ParamField>

        <ParamField path="sorts" type="object[]">
          List of fields to sort the results by.

          <Expandable title="sort properties" defaultOpen="true">
            <ParamField path="field" type="string" required>
              The field name to sort by.
            </ParamField>

            <ParamField path="desc" type="boolean" default="false">
              When set to `true`, sorts the field in descending order. Omit or set to `false` to sort in ascending order.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField path="topic" type="string">
          The name of the topic used in the query, if applicable.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="description" type="string" required>
      A human-readable description of what the query does or what insights it provides.
    </ParamField>

    <ParamField path="hidden" type="boolean" default="false">
      When set to `true`, hides the query from being presented as an example query in the workbook or embedded Omni Agent.
    </ParamField>

    <ParamField path="prompt" type="string">
      A natural language prompt that represents how a user might ask for this query. Used by the Omni Agent.
    </ParamField>

    <ParamField path="ai_context" type="string">
      Additional context to help the Omni Agent understand how to use this query or what it demonstrates.
    </ParamField>

    <ParamField path="exclude_from_ai_context" type="boolean" default="false">
      When set to `true`, excludes this query from the model's AI context, preventing the AI from using it as a reference.
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml theme={null}
sample_queries:
  Summary Stats:
    query:
      fields: [ order_items.sale_price_sum, users.count, calc_1 ]
      base_view: order_items
      calculations:
        calc_1:
          sql: OMNI_FX_SAFE_DIVIDE(${order_items.sale_price_sum}, ${users.count})
      limit: 1000
      sorts:
        - field: order_items.sale_price_sum
          desc: true
      topic: order_items
    description: Total Revenue, Users and Revenue per User
    hidden: false
    prompt: show me total revenue, count of users and revenue per user
    ai_context: uses a calculation to compute avg. revenue per user
    exclude_from_ai_context: false
```