> For the complete documentation index, see [llms.txt](https://help.tellius.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.tellius.com/tellius-6.4/data/kaiya-context-model.md).
# Kaiya Context Model
The grounded meaning of a datasource that Kaiya answers from: tables, relationships, metrics, vocabulary, rules and analyses, built in the chat.
A Kaiya context model holds what Kaiya needs to know about one datasource to answer questions on it correctly. It lists the tables Kaiya can use, how they join, how each metric is calculated, what your business terms mean, and the rules Kaiya must follow. Kaiya reads the model before it writes a query, so its answers follow your definitions instead of its own guesses.
You build a context model by talking to Kaiya. Kaiya asks which datasource and tables to model, checks the joins against the real data, proposes metrics and business terms, and asks before it saves anything. Each save creates a new version that you can compare with the one before. As soon as a model is saved, Kaiya answers on it, and you can build Kaiya Apps and Kaiya Missions on top of it.
A context model can also grow on its own. When people explain what a term means in their conversations, Kaiya collects those explanations and suggests them as changes to the model. The model's owner, or someone who can edit the model, approves the ones that fit and publishes them to the model as a new version. See [Context model suggestions](https://help.tellius.com/data/kaiya-context-model/context-model-suggestions).
{% hint style="info" %}
Kaiya context models are new in Tellius 6.4, and they are built on live data sources. Each role decides who can use them, with the **Context Models** module under **Settings → Workspace → Users & Access → Roles**. See [Who can work with a context model](#who-can-work-with-a-context-model).
{% endhint %}
### Where to find context models
Open **Data** and select the **Context Models** tab, next to **Business View**. The tab lists every context model you can open, and **New context model** starts a new one. The tab appears when your role has **Read Access** or **Full Access** to **Context Models**. You can also pick a context model in the data picker of the Kaiya chat box, and of the ask box on the home page, to ask questions on it. See [Exploring and editing a context model](https://help.tellius.com/data/kaiya-context-model/exploring-and-editing-a-context-model).
### What a context model holds
| Part | What it holds | Example |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Tables** | The tables Kaiya can query. Each table has a description, its grain (what one row stands for), a row count and its columns, with each column's role, data type, synonyms and aggregation. | A territory table with one row per territory. |
| **Relationships** | Named joins between tables. Each one has its join keys, its cardinality (for example, many to one), a fan-out guard and a "use when" note that tells Kaiya which questions the join is meant for. | Weekly prescriptions join to the HCP table on the HCP ID, to break prescriptions down by specialty. |
| **Metrics** | Calculations written in the datasource's own SQL, with a description, synonyms and a display format. | Market share: our product's TRx divided by the TRx of every product in the market. |
| **Vocabulary** | Business terms, what they mean, and what each one maps to in the data, usually a filter. | "Competitors" means every product in the market that isn't ours. |
| **Rules** | Instructions Kaiya follows when it answers, with the tables or metrics each rule applies to and, where needed, when it applies. | Combine two fact tables at their shared key, never through a dimension they share. |
| **Analyses** | Step-by-step recipes for the questions your business asks most often. | How to find the territories that are underperforming. |
| **Calendar** | The calendar Kaiya uses to read periods such as "this fiscal quarter" or "last 13 weeks". Kaiya takes it from the calendar set up for the datasource, in the same way as a Business View does. When no calendar is set, Kaiya uses the standard (Gregorian) calendar. The model also has a default date column, which Kaiya uses for time questions unless you name another date. The calendar and the default date column show only in the **YAML** tab, not in **Explore**. See [Custom Calendars for Live Connections](https://help.tellius.com/data/preparing-your-business-views/custom-calendars-for-live-connections) and [Setting up custom calendars](https://help.tellius.com/data/preparing-your-business-views/setting-up-custom-calendars). | "This fiscal quarter" means the current quarter of your company's fiscal year, not of the calendar year. |
{% hint style="info" %}
**Fiscal periods need a calendar.** If your business reports in fiscal weeks, months or quarters, set up the datasource's calendar before you build a model on it: a new model picks up the calendar that's set for its datasource. If Kaiya can't read the calendar when it answers, it uses standard dates and tells you that it couldn't work out the fiscal periods.
{% endhint %}
### How a context model differs from a Business View
Both give Kaiya a business-friendly layer over your data. They differ in how you build them, how they change, and where you can use them.
| | Business View | Kaiya context model |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **How you build it** | Create datasets from a datasource, then create the Business View and publish it. Kaiya Architect can do these steps for you in the chat. | Connect a datasource and build the model in one conversation. There are no datasets to create, no publish job, and no copy of the data built for the model. |
| **Where queries run** | Live on the datasource, or on data pre-loaded into Tellius. | Live on the datasource. Support for non-live models is planned. Kaiya queries only what each question needs, so the model works even when it covers many large tables. |
| **Joins** | Set when the Business View is created. | Named relationships, each with a note on when to use it, so Kaiya picks the join that fits the question. |
| **Calculations** | Calculated columns. | Metrics written in the datasource's own SQL. |
| **Business knowledge** | Column names, descriptions and synonyms. | The same, plus vocabulary, rules and analyses. |
| **Changes** | Edit the Business View and publish it again. | Save a new version in seconds. Every version is kept and can be compared with the one before. |
| **Where you can use it** | Kaiya, Vizpads, Search and the other Tellius modules. | Kaiya conversations, Kaiya Apps and Kaiya Missions. |
### When Kaiya builds or uses a context model
* **New conversations build a context model by default.** When your role has **Full Access** to **Context Models** and you ask about data that has no model yet, Kaiya offers to build a context model. It builds a Business View only when you ask for one. See [Building a context model in the conversation](https://help.tellius.com/data/kaiya-context-model/building-a-context-model-in-the-conversation).
* **A context model comes first.** When both a context model and a Business View could answer a question, Kaiya answers from the context model.
* **Answers say where they came from.** An answer that used a context model shows **Based on** followed by the model's name under the answer.
* **With Read Access to Context Models,** Kaiya answers on the context models you can open, but it doesn't build or change a model for you.
* **With No Access to Context Models,** Kaiya works on Business Views only, context models are hidden from you, and Kaiya Architect builds Business Views. See [Kaiya Architect Agent](https://help.tellius.com/data/kaiya-architect-agent).
{% hint style="success" %}
**Context model or Business View?**
* Choose a **context model** when people will mainly work with the data through Kaiya: questions, Kaiya Apps and Kaiya Missions. It's quicker to build and change, it carries your business terms and rules, and it can learn from conversations.
* Choose a **Business View** when you need Vizpads or dashboards, or what-if dynamic parameters.
* You don't have to choose once and for all. Existing Business Views keep working as they do today, and you can turn one into a context model with **Migrate a Business View**. The Business View itself isn't changed.
{% endhint %}
### Who can work with a context model
Two things decide what you can do with a context model: your role, and the access you have to the model itself.
**Your role.** Each role has a **Context Models** module in its **Kaiya** group, under **Settings → Workspace → Users & Access → Roles**. The module needs **Chat** at **Read Access** or higher. See [Custom roles](https://help.tellius.com/settings/users-and-access/custom-roles).
| Level | What the user can do with context models |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No Access** | Nothing. The **Context Models** tab is hidden, the data picker lists no context models, and Kaiya answers from Business Views. |
| **Read Access** | Open the **Context Models** tab and the models they can open, read every tab of a model, see its suggestions, and pick models in the chat to ask questions on them. They can't create, edit, share, archive or delete a model, decide suggestions, or have Kaiya build or change a model. |
| **Full Access** | Everything in **Read Access**, plus create models, build and update them in the chat, share them, and decide their suggestions, within the model's own access below. Creating a model also needs **Full Access** to **Chat** and **Datasets**. |
**The model's own access.** For people whose role has **Full Access** to **Context Models**, each model also has its own access:
* **Edit:** the model's owner, an admin, or anyone the model is shared with using **Can Edit** access.
* **Delete:** the model's owner or an admin.
To let someone help maintain a model, share it with **Can Edit**. See [Sharing a context model](https://help.tellius.com/data/kaiya-context-model/exploring-and-editing-a-context-model#sharing-a-context-model).
Row-level access applies here too. When Kaiya answers on a context model, each user's Security Tags limit the rows they see, in the same way as in the rest of Kaiya. See [Security Tags](https://help.tellius.com/settings/users-and-access/security-tags).
{% hint style="success" %}
**Read Access or Full Access?** Give **Read Access** to people who ask questions on models that others maintain, such as analysts and business users. Give **Full Access** to the people who build models and keep them right. A **Can Edit** share doesn't let someone change a model while their role has only **Read Access**, so check the role first when someone can't edit a model that was shared with them.
{% endhint %}
{% hint style="info" %}
**Can view or Can Edit?** Share with **Can view** when people only need to read and use the model. Share with **Can Edit** when they help keep it right, such as fixing a metric or approving suggestions. Can Edit never lets someone delete the model: only its owner or an admin can do that.
{% endhint %}
### Limits in Tellius 6.4
* **Supported sources.** In Tellius 6.4, a context model is built on a live data source, and Kaiya queries the source directly. A few of the structured datasources that Tellius connects to are supported today. Support for non-live models and many more sources is planned. See [Step 2: Live or non-live](https://help.tellius.com/data/kaiya-context-model/building-a-context-model-in-the-conversation#step-2-live-or-non-live).
* **Not in Vizpads.** Vizpads and dashboards still use Business Views.
* **No dynamic parameters.** What-if parameters are available on Business Views only. See [Creating dynamic parameters](https://help.tellius.com/data/preparing-your-business-views/creating-dynamic-parameters).
* **Who can use it.** Each role's **Context Models** module decides who can use context models. There is no switch for the whole workspace. In a new workspace, the built-in roles start at **Full Access**, and a new custom role starts at **No Access**. In earlier Tellius 6.4 builds, a super user turned context models on or off for the whole workspace with **Enable Kaiya Context Models** in Kaiya Configuration. When roles took over, each role kept the access that setting gave it: **Full Access** if it was on, and **No Access** if it was off. Super User always has **Full Access**, and a role with **Chat** at **No Access** has **No Access** to **Context Models**.
### In this section
* [Building a context model in the conversation](https://help.tellius.com/data/kaiya-context-model/building-a-context-model-in-the-conversation): every question Kaiya asks, from choosing the tables to saving version 1, and how to update the model later.
* [Exploring and editing a context model](https://help.tellius.com/data/kaiya-context-model/exploring-and-editing-a-context-model): the **Context Models** tab, the **Explore**, **Diagram**, **YAML** and **Versions** tabs, editing the YAML, comparing versions, sharing and archiving.
* [Context model suggestions](https://help.tellius.com/data/kaiya-context-model/context-model-suggestions): how Kaiya learns from conversations, how to approve, publish or reject suggestions, and the settings that control them.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://help.tellius.com/tellius-6.4/data/kaiya-context-model.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
