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

# sample_queries

> Defines a list of sample queries that could be performed on the topic.

Defines a list of sample queries that could be performed on the topic, which is used:

* **To present example queries** when a topic is selected in the workbook or using the [Omni Agent](/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 topic's AI context, set the `exclude_from_ai_context` to `true`.

You can add a workbook query to this parameter using one of the following methods:

* **From the Model menu**: Click **Model > Save as sample query to topic** in the workbook.
* **From the inspector**: Click the <Icon icon="bug" iconType="solid" /> near the bottom left corner of the page to open the [workbook inspector](/analyze-explore/workbook-inspector). Click **Copy query and visualization YAML** in the inspector header to copy the query and visualization configuration in the sample query format, then paste it into your topic file in the model IDE.

## 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.
        </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" default="false" type="boolean">
      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" default="false" type="boolean">
      When set to `true`, excludes this query from the topic'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
```