# Query Learning

A **Query Learning** fixes how Kaiya should interpret a full question pattern (aggregation, grouping, filters, time windows, ranking). It must include an **Intent** so Kaiya can reuse the learning for similar phrasings.

1. Navigate **Kaiya → Open Side Bar → Manage Learnings → Query Learnings**. The following page will be displayed. 

<figure><img src="https://content.gitbook.com/content/8GaK1h3pmgbR63x0ftET/blobs/7Y9Pi1thoivsTAh6EtZL/image.png" alt=""><figcaption></figcaption></figure>

2. You can sort and order the Learnings as follows.

<figure><img src="https://content.gitbook.com/content/8GaK1h3pmgbR63x0ftET/blobs/9Ckdv3iKhXYPlPVBkgzR/image.png" alt="" width="287"><figcaption></figcaption></figure>

3. The following will be displayed for each Learning:

* **Query:** literal phrase/alias for which the Learning has been created
* **Intent/mapping:** the resolved meaning for the phrase
* Creator name, created time. and the timestamp of last update.
* Click on the three-do kebab menu to edit or delete a Learning.

{% hint style="warning" %}
Query Learnings are org-wide patterns. You’ll notice there’s no **Learning Level** or **Selected Business View** field in the Query Learning dialog; only admins can create them and they apply across the org. BV is resolved at run time from the user’s active context. If you need per-user or per-BV semantics, use Phrase Learnings.
{% endhint %}

4. Click on **Create Learning** button and the following window will be displayed.&#x20;

<figure><img src="https://content.gitbook.com/content/8GaK1h3pmgbR63x0ftET/blobs/tG2rz1vS2904n7nEbUpK/image.png" alt="" width="563"><figcaption></figcaption></figure>

5. **Query:** Enter a representative natural-language question users actually ask. Avoid single-word aliases like supplier → use **Phrase Learning** for that.
6. **Query Type:** Choose whether you want to add an analytical query or a compound query.

* **Analytical Query -** Use for a single analysis pattern (one result set) with clear aggregation/grouping/time/filter/ranking. Examples: Top-N per group; threshold + grouping; single MoM/YTD compare.
* **Compound Query -** Use for questions that combine multiple analytical operations into one Learning (multi-step or multi-output logic you want treated as a unit). Examples: *“Show MoM revenue by channel and highlight segments where TRx > 150.”, “Compare actual vs plan vs forecast by region with a ranked variance list.”*

7. **Intent:** Briefly describe in natural language what the query is intended to achieve. This helps Kaiya understand and apply the Learning accurately. Include:
   * **Aggregation(s):** sum/avg/count/calculation names
   * **Grouping:** the exact “group by” fields
   * **Filters/thresholds:** value conditions, segments
   * **Time logic:** window and/or Period A vs Period B
   * **Ranking/limits:** order by, Top-N, partitions

{% hint style="warning" %}
**Why Intent is mandatory?**

Different phrasings (“top three per region”, “best 3 by region”) map to the same structured action because the **Intent** is the anchor. With **Intent**, Kaiya doesn’t rely on exact tokens; it “knows” what to build even if synonyms or order change, reducing follow-up questions.
{% endhint %}

8. **Custom Mappings:** Turn on to bind tokens from the query to exact Business View fields, eliminating column ambiguity. Ideal for situations when multiple synonyms or overlapping names exist. Click on **Add Mapping** and the following window appears.

<figure><img src="https://content.gitbook.com/content/8GaK1h3pmgbR63x0ftET/blobs/VtnEBwTxATfbefmdfTaF/image.png" alt="" width="262"><figcaption></figcaption></figure>

9. **Mapped Phrase:** The exact token from the query you’re pinning. Kaiya will resolve this token using the mapping you define.
10. **Type:** What kind of thing the phrase represents.

* **Aggregation:** Picks the metric and how to roll it up. Use when the word should always resolve to a specific metric/aggregation.
* **Dimension:** Sets the *“group by”* field to break down results.
* **Resolution:** Sets the time grain used for grouping without adding a date filter. Use for phrases like *“weekly revenue”.*
* **Filter:** Applies a non-time condition on a column
* **Time filter:** Constrains the time window or comparison periods

11. **Business View:** The specific BV that contains the column you want to bind to.
12. **Column:** The exact field in that BV to map to (pick the modeled measure with its aggregation, or the precise dimension/flag).
13. Click on **Apply** to save the Learning, or click on **Cancel** to dismiss.
14. Finally, click on **Save Changes** to create the Learning. Or click on **Cancel** to dismiss.
15. If you want to delete a Learning, click on **Delete Learning** button. All the above fields are applicable when editing a Learning.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.tellius.com/kaiya/kaiya-conversational-ai/kaiya-learnings/query-learning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.