> 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/building-a-context-model-in-the-conversation.md).
# Building a context model in the conversation
Build a Kaiya context model by answering Kaiya's questions in the chat, then ask questions on it and update it.
You build a Kaiya context model in a Kaiya conversation. Kaiya does the work: it reads the tables, measures how they join, writes the metrics and business terms, and checks the result against the data. You steer it by answering a short series of questions. Nothing is saved until you say so.
### Before you start
* Your role needs **Full Access** to the **Context Models** module, and **Full Access** to **Chat** and **Datasets**. An administrator sets these under **Settings → Workspace → Users & Access → Roles**. With **Read Access** to **Context Models**, you can ask questions on saved models, but Kaiya doesn't build or change a model for you. See [Who can work with a context model](https://help.tellius.com/data/kaiya-context-model#who-can-work-with-a-context-model).
* The datasource you want to model must already be connected. See [Connect](https://help.tellius.com/data/connect).
* In Tellius 6.4, context models are built on live data sources. Support for non-live models and more sources is planned.
### Three ways to start
* **Ask in a new conversation.** Ask a question about data that has no context model or Business View yet, or ask for a model directly. For example: *"Build a Kaiya context model. Ask me which datasource and tables to model, then build and save it."*
* **From the Data page.** Open **Data → Context Models**, select **New context model**, then select **Build with Kaiya**. A conversation opens and Kaiya starts asking which datasource and tables to model.
* **From an existing Business View.** Open **Data → Context Models** and select **New context model**. Under **Migrate a Business View**, pick a view from the **Business View** list, then select **Migrate with Kaiya**. The button stays inactive until you pick a view. Kaiya writes a new context model from the view in the chat, carries over the view's column settings, and tells you what couldn't carry over. The Business View itself isn't changed and keeps working as before.
The dialog opens with **Build with Kaiya** selected. Either choice opens a new Kaiya conversation, as the note at the bottom of the dialog says. Select **Cancel** or the **X** to close the dialog without starting anything.
Watch a one-minute walkthrough, or follow the steps below.
{% embed url="" %}
{% hint style="success" %}
**Build from scratch or migrate?** Migrate when a Business View already holds the joins and calculations your team trusts: you keep that work and gain vocabulary, rules and versions on top. Build from scratch when you're starting on new tables, or when the existing view mixes several subjects that would read better as a focused model.
{% endhint %}
### How Kaiya's question cards work
Each step below is a question card in the chat. A card has a short header, the question, and numbered options. Kaiya marks the option it suggests with **(Recommended)**. Kaiya words each question itself, so the headers and options you see can differ slightly from the examples on this page.
* Select an option, or press its number on the keyboard and then press Enter to confirm.
* To answer in your own words, type in **Or type your own...** instead.
* Some cards accept more than one choice. These show checkboxes and a free-text **Other** option.
* **Skip** moves on without answering, and **Submit** sends your answer.
* While a card waits for you, the chat shows **Waiting for your answer**.
After you answer, the cards fold into one line, **Answered · N questions**, followed by a short summary of your answers. Expand it to page through each question and the option you chose.
The last step, saving the model, isn't a question card. Kaiya asks for your approval in a separate card instead. See [Step 8: Save the context model](#step-8-save-the-context-model).
To follow the work as it happens, open **How Kaiya got this** on the answer. Steps such as **Reading a table's columns**, **Querying the datasource**, **Opening the context model**, **Working on the context model**, **Checking the context model** and **Saving the context model** show what Kaiya is doing. A step marked **Corrected** is one where Kaiya found a problem in its own work, for example a name the model doesn't accept, and fixed it before going on.
### Step 1: What to build
When Kaiya finds no Business View or context model that covers your data, it tells you what you can query today and asks what to build:
* **Business View:** a published, queryable view of the data that people can analyze, and build Apps and Missions on.
* **Kaiya context model:** a versioned model of the datasource's tables, metrics, vocabulary and rules that Kaiya answers questions on.
Choose **Kaiya context model** to continue on this page. If you choose **Business View**, Kaiya Architect builds a Business View instead. See [Creating a new Business View workflow](https://help.tellius.com/data/kaiya-architect-agent/creating-a-new-business-view-workflow).
### Step 2: Live or non-live
Kaiya asks how the model should reach the data. It won't open the tables until you answer. In Tellius 6.4, context models are built on live sources, so choose **Live**.
* **Live:** every query runs in place on one connected database datasource, so answers always reflect the current data.
* **Non-live:** non-live context models are planned. They aren't available in Tellius 6.4.
{% hint style="info" %}
**A live model reads the source every time.** Each question runs on the datasource itself, so the model works best on a warehouse that is fast enough for interactive questions. The **Context Models** list and each model's page show whether a model is live.
{% endhint %}
{% hint style="info" %}
**No refresh to schedule.** A live context model always reads the current data in the source, so there is nothing to refresh. The only scheduled job on a context model is the daily suggestions run. See [Context model suggestions](https://help.tellius.com/data/kaiya-context-model/context-model-suggestions).
{% endhint %}
### Step 3: Choose the tables
Kaiya lists the tables in the datasource that relate to your request and offers a few sets to choose from. For example, a core set of tables, the core set plus activity and territory tables, or everything related to the subject. Each option lists the tables it includes. Pick a set, or type your own list.
### Step 4: Kaiya measures the data
Kaiya now reads each table's columns and runs queries against the data. It checks:
* **Grain:** what one row stands for in each table, for example one row per prescriber, product and week.
* **Row counts and key formats:** so it knows which columns can join.
* **Join coverage:** for each possible join, how many keys match on both sides and how many rows survive the join.
* **Fan traps and chasm traps:** joins that would repeat rows and inflate totals, especially when two fact tables share a dimension.
On large tables this can take several minutes. You can follow each query in **How Kaiya got this**.
### Step 5: Review the context model plan
Kaiya shows the measured plan in a **Context model plan** card. It lists:
* each table with its grain and row count,
* each relationship with its keys, how many keys matched, the row count before and after the join, its cardinality, and a ✅ or ⚠️ status,
* a summary of the join coverage, with a plain explanation and a suggested fix for every join that warns about low coverage,
* any chasm-trap risk, with a note that Kaiya will add up each side to the shared key first.
Choose one option:
* **Looks good, proceed:** accept the tables and relationships as measured.
* **I want to make changes:** change tables, keys or joins before Kaiya adds metrics, vocabulary, rules and analyses.
{% hint style="warning" %}
**Read the ⚠️ joins before you approve.** Low coverage often has a good reason. For example, a product table may list only branded products, so most generic products find no match. Kaiya's note tells you why it thinks coverage is low and what it would do. If the reason doesn't match your business, choose **I want to make changes**.
{% endhint %}
### Step 6: Make changes (optional)
If you chose **I want to make changes**, Kaiya asks **What would you like to change before I go on?** The checkboxes depend on your plan. Typical choices are:
* drop specific joins, such as the low-coverage ones,
* **Change the tables:** add tables to the model or remove them,
* **Keep the joins, change the grain or keys,**
* **Other:** anything else, in your own words. For example, *"Can you create some metrics and vocabulary that are relevant for this?"*
Kaiya makes the changes, measures again where needed, and shows the plan again.
### Step 7: Kaiya adds metrics, vocabulary, rules and analyses
Kaiya writes the rest of the model:
* **Metrics** in the datasource's own SQL, such as market share or prescriptions by type.
* **Vocabulary** for your business terms, such as what "branded market" or "active prescriber" means.
* **Rules** Kaiya must follow, such as never adding aggregate rows to the individual rows they summarize.
* **Analyses** for common questions.
Kaiya then checks the model's structure and runs two or three key questions on the draft. These draft checks catch joins that leave many empty values, totals inflated by a fan-out, and dimensions that come back empty. A second **Context model plan** card lists each draft check with its status, the value it returned and a note, and says how many metrics, terms, rules and analyses it added. Choose **Looks good, proceed** to go on to saving, or **I want to make changes**.
### Step 8: Save the context model
Before it saves, Kaiya sums up what the model covers: its tables, relationships, metrics, business terms and rules. It then asks for your approval in a **Permission required** card in the chat. The card asks whether to save the context model Kaiya just summed up, and tells you that Kaiya will answer on it right away.
* **Allow once:** Kaiya saves the model as version 1 and answers on it from now on. The context model card in the chat changes from **Draft · not saved yet** to **Saved · v1**.
* **Deny:** nothing is saved, and the draft stays as it is. Kaiya asks what you'd like to change, and it doesn't ask to save again in the same turn.
Your approval covers only the model as Kaiya summed it up. If the model changes after you approve, Kaiya asks again before it saves.
{% hint style="info" %}
**Kaiya always asks before it saves.** Kaiya won't save a model until the joins are measured, you have agreed to the plan, the draft has passed its checks, and you have selected **Allow once** on the approval card. If you ask it to save sooner, it finishes the missing steps first. A "yes" typed in the chat doesn't count as approval: saving always goes through the approval card.
{% endhint %}
### The draft beside the conversation
While Kaiya builds, the model opens in a panel beside the chat. The panel shows the model's name with **Draft · not saved yet** and the note **Not saved yet. Kaiya asks before it saves.** It also shows the number of tables, columns, relationships and metrics, whether the model is live, and the datasource type. Once saved, the note changes to **Saved. Kaiya answers from this version.**
The panel has three tabs:
* **Explore:** the model's tables, relationships, metrics, vocabulary, rules and analyses.
* **Diagram:** the tables and their joins. Select **Auto layout** to arrange the tables neatly, **Show N columns** or **Hide columns** on a table card, and the zoom controls to zoom in, zoom out or fit the diagram. Each relationship card below the diagram shows the join keys, the cardinality, such as many to one, and its "use when" note.
* **YAML:** the model as it is written.
Select the context model card in the chat to open the panel again, and **Close context model** to close it. These tabs work the same way as on the Data page. See [Exploring and editing a context model](https://help.tellius.com/data/kaiya-context-model/exploring-and-editing-a-context-model).
### Asking questions on a context model
Once a model is saved, ask questions in plain language, as you would on a Business View. To pick a model yourself, use the data picker in the chat box: context models are listed under **Context models**, next to **Business views**. The data picker in the ask box on the home page lists them too, so you can start a new conversation on a context model. You can pick more than one model when they are on the same datasource. A model on a different datasource from the one in use is marked **Different datasource**.
For each question, Kaiya reads the parts of the model it needs, works out the time window, and writes the query from the model's own metrics, terms and rules. An independent review then checks the result before Kaiya answers. In **How Kaiya got this**, the review step shows a verdict: **Pass** when it found no issues, or a request to regenerate when it found something to fix, after which Kaiya runs the query again. Notes marked **Worth verifying** point to anything you may want to check yourself, and **Read full review** opens the full review.
An answer built on a context model shows **Based on** and the model's name under the answer.
{% hint style="success" %}
**Check what was grounded.** After an analysis, ask *"What part of this analysis was not grounded in the context model?"* Kaiya separates what came from the model (its metrics, terms and rules) from what it brought in itself, such as a grouping it defined, a default time window it chose, or its reading of the results. You can then ask Kaiya to add those items to the model, so every later answer reads them from the model instead.
{% endhint %}
### Updating a context model in the conversation
To change a saved model, ask Kaiya in a conversation. For example, *"Add a metric for our share of the class"* or *"Add 'big three' to the vocabulary."* Kaiya edits the model, checks it, and sums up what changed since the version you opened. It then asks for your approval again in a **Permission required** card, this time to save the changes as the next version. When you select **Allow once**, the context model card shows the new version, such as **Saved · v2**. While Kaiya edits, the panel shows **Editing vN · not saved**.
If someone else saved a newer version while you were working, Kaiya tells you, opens the latest version and applies your change to it again before it asks to save.
A change you save in the conversation is live right away: there is no separate publish step. Suggestions work differently: approved suggestions reach the model when someone publishes them on the model's **Suggestions** tab. Each save keeps the earlier versions, and you can compare any version with the current one on the Data page. You can also build Kaiya Apps and Kaiya Missions on a saved model and keep improving the model afterwards.
{% hint style="info" %}
**When to update the model and when not to.** Add something to the model when everyone who uses it should read it the same way, such as an agreed definition of a metric or a business term. Keep a one-off choice in your conversation instead, such as a time window for a single question. Until a change is saved in the model, it applies only in the conversation where you made it. See [Context model suggestions](https://help.tellius.com/data/kaiya-context-model/context-model-suggestions).
{% endhint %}
---
# 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/building-a-context-model-in-the-conversation.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.
