> 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/exploring-and-editing-a-context-model.md).

# Exploring and editing a context model

Find, open, explore, edit, compare, share, archive and delete Kaiya context models from the Context Models tab on the Data page.

Every Kaiya context model you can open is listed on the **Data** page, in the **Context Models** tab next to **Business View**. From there you can read everything the model holds, see its joins as a diagram, edit its YAML, compare versions, review suggestions, and share, archive or delete it.

{% hint style="info" %}
The **Context Models** tab appears only when your role has **Read Access** or **Full Access** to the **Context Models** module. With **Read Access**, you can open and read models but not change them: creating, editing, sharing, archiving and deleting a model need **Full Access**. See [Who can work with a context model](https://help.tellius.com/data/kaiya-context-model#who-can-work-with-a-context-model).
{% endhint %}

Watch a one-minute walkthrough, or read the sections below.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC5PhRxmOjkQZJEO6F9Zw%2Fuploads%2Fnfsj6JED6B56ym9g1SDY%2Fkcm-tour-v6.mp4?alt=media&token=e29b810b-a2f5-453b-b9bf-622f91790903>" %}

### The Context Models list

The list is a table with these columns:

* **Name:** the model's name, its current version (for example, **v1**), an **Archived** tag for an archived model, and its description.
* **Datasource:** the datasource's icon and name, and a **Live** or **Non-live** tag.
* **Owner:** who owns the model.
* **Updated:** when the model was last saved.

Select anywhere on a row to open the model.

Use the controls above the list to narrow it down:

* **Search context models:** find a model by name.
* **All**, **Mine**, **Shared with me** and **Archived:** show every model you can open, only the models you own, only the models others have shared with you, or only archived models. Archived models don't appear in the other tabs.
* **Datasource:** once your models use more than one datasource, pick one to list only its models, or **Non-live** for models that aren't on a live datasource.

Each row has a menu (three dots) with **Share**, **Archive** (or **Unarchive** for an archived model) and **Delete**. You see only the actions you can take: **Share** needs a role that can share context models, and **Archive** and **Delete** are for the model's owner or an admin.

<figure><img src="https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC5PhRxmOjkQZJEO6F9Zw%2Fuploads%2FbYhghtbAE7dpAglTi0D5%2Fcm-list-archived-tab.png?alt=media" alt="The Context Models list, with the All, Mine, Shared with me and Archived tabs" width="563"><figcaption></figcaption></figure>

<figure><img src="https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC5PhRxmOjkQZJEO6F9Zw%2Fuploads%2FplzwbaIakW81JcQIKk8I%2Fcm-list-row-menu.png?alt=media" alt="The row menu in the Context Models list, with Share, Archive and Delete" width="563"><figcaption></figcaption></figure>

When there are no models yet, the tab shows **No context models yet** with two buttons, **Build with Kaiya** and **Migrate a Business View**.

### Creating a context model

Select **New context model**. The dialog offers two ways to start:

* **Build with Kaiya:** opens a conversation in which Kaiya asks which datasource and tables to model, checks them against the data, and saves the model when you agree.
* **Migrate a Business View:** pick a view from the **Business View** list, then select **Migrate with Kaiya**. Kaiya writes a new context model from the view and shows what couldn't carry over. The view isn't changed.

**Cancel** or the close icon closes the dialog. Both paths continue in the chat. See [Building a context model in the conversation](https://help.tellius.com/data/kaiya-context-model/building-a-context-model-in-the-conversation).

<figure><img src="https://1702728550-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC5PhRxmOjkQZJEO6F9Zw%2Fuploads%2FjiYYDdQ5C5ZyUosczyDa%2Fcm-new-context-model-dialog.png?alt=media&#x26;token=cae661ff-6676-47bf-bf49-9b4efe5a5788" alt="The New context model dialog, with Build with Kaiya and Migrate a Business View" width="563"><figcaption></figcaption></figure>

### The context model page

Opening a model shows its page. The header holds:

* the back arrow, which returns to the list,
* the model's name, with a **Live** or **Non-live** tag and, for a live model, its datasource type (for example, **Snowflake**),
* **Version:** lists every saved version, with the current one marked **(current)**. Pick an older version to read it. The page then shows **Viewing vN (read-only)** and **Back to current version**, and nothing can be changed until you go back to the current version.
* **Edit**, and a menu (three dots) with **Share**, **Archive** (or **Unarchive**) and **Delete**. The menu is hidden while you edit.

The tabs below the name are **Explore**, **Diagram**, **Suggestions**, **Versions** and **YAML**. The **Suggestions** tab appears only when suggestions are turned on, and shows how many are pending. See [Context model suggestions](https://help.tellius.com/data/kaiya-context-model/context-model-suggestions).

<figure><img src="https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC5PhRxmOjkQZJEO6F9Zw%2Fuploads%2FONsUskHrfHricNpfYoji%2Fcm-header-menu.png?alt=media" alt="The menu in a context model&#x27;s header, with Share, Archive and Delete" width="563"><figcaption></figcaption></figure>

### Explore

**Explore** shows the model's description and its tables. **In this model**, on the left, lists the parts of the model with how many items each holds: **Tables**, **Relationships**, **Metrics**, **Vocabulary**, **Rules** and **Analyses**. Use it to move between the sections.

| Section           | What each row shows                                                                                                                                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tables**        | The table's display name, its name in the datasource, a green dot when it is live, its row count and its number of columns.                                                                                       |
| **Relationships** | **Joins** (which table joins to which), **Use when** (the questions the join is meant for), **Cardinality**, **Fan-out guard**, **Join on** (the exact key match) and **Technical name**.                         |
| **Metrics**       | **Metric**, **Description**, **Synonyms** (other words people use for it), **Format** (for example, a percentage with one decimal), **Formula** (the calculation in the datasource's SQL) and **Technical name**. |
| **Vocabulary**    | **Term**, **Means** (what the term stands for in your business) and **Maps to** (what it becomes in a query, usually a filter).                                                                                   |
| **Rules**         | **Name**, **Description**, **Applies to** (the tables or metrics it covers), **Use when**, **Rule** (the instruction itself) and **Technical name**.                                                              |
| **Analyses**      | Step-by-step recipes for the questions the business asks most. **No analyses yet** means the model has none so far.                                                                                               |

Cards at the right show the model's state at a glance:

* **Suggestions** (when suggestions are on): how many are pending and when Kaiya last ran.
* **Used by:** the Missions, Apps and conversations that use the model, or **No mission, app or conversation uses this model yet.**
* **Versions:** the latest version, with **All versions** to open the **Versions** tab.

<figure><img src="https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC5PhRxmOjkQZJEO6F9Zw%2Fuploads%2FY1URIWr2z1cl7LAbbLWk%2Fcm-explore-redesign.png?alt=media" alt="The Explore tab, with the In this model list on the left and the Used by and Versions cards on the right" width="563"><figcaption></figcaption></figure>

#### Opening a table

Select a table to see its details. The table page shows its description, its grain (for example, **One row per TERRITORY\_ID**), its row count and how many measures it has. Below that:

* **Columns** lists every column with **Display name**, **Role** (for example, **Dimension**), **Description**, **Synonyms**, **Aggregation**, **Point in time**, **Security tag** and **Data type**. Use **Search columns** to find one.
* **Relationships** lists only the joins that involve this table. **Not joined** means no relationship connects the table to the rest of the model.

Select the back arrow beside the table name to return to the model.

{% hint style="success" %}
**Read the "use when" notes first.** Unlike a Business View, a context model can hold several ways to join the same tables. The **Use when** note on each relationship and rule is how Kaiya decides which one fits a question. If Kaiya picks the wrong join for your question, the note is usually the thing to fix.
{% endhint %}

### Diagram

**Diagram** draws the tables and their joins.

* Each table card shows the table name, whether it is a fact or a dimension table, and its number of columns. Select **Show N columns** to list the columns on the card, and **Hide columns** to fold them away.
* Lines between cards show each join with its cardinality, for example **N:1** (many to one).
* Select **Auto layout** to arrange the cards neatly. Use the zoom controls at the bottom left to zoom in, zoom out, or fit the whole diagram on screen. Selecting a table highlights it, and **Clear selection** removes the highlight.
* Beside the diagram, **Relationships** lists one card per join, with the key match, the cardinality and the "use when" note. On a narrow screen, the list sits below the diagram.

<figure><img src="https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC5PhRxmOjkQZJEO6F9Zw%2Fuploads%2FEtgbs7W9qbKLCZQjOHFh%2Fcm-diagram-relationships.png?alt=media" alt="The Diagram tab, with the Relationships list beside the diagram and Auto layout" width="563"><figcaption></figcaption></figure>

If the YAML has an error, the diagram can't be drawn and the tab shows the error instead.

### YAML

**YAML** shows the whole model as it is stored: vocabulary, tables, columns, relationships, metrics, rules and analyses, the calendar and the default date column, with the version number. The calendar and the default date column appear only here, not in **Explore**. The tab is read-only until you select **Edit**.

#### Editing the YAML

You can edit a model if you own it, if you are an admin, or if it is shared with you with **Can Edit** access. In each case, your role also needs **Full Access** to **Context Models**.

1. Select **Edit**. The **YAML** tab opens as an editor, and the header shows **Cancel**, **Validate** and **Save as new version**. The **Version** list is inactive while you edit.
2. Make your change in the editor.
3. Select **Validate** to check the model. Kaiya reports **The model is valid.** or the number of problems to fix.
4. Select **Save as new version**. The model is saved as the next version, and Kaiya answers from it straight away. To drop your changes, select **Cancel** instead.

If someone else saved a version while you were editing, the save stops and asks you to load the latest version into the editor and apply your change again. Select **Load latest** to do that. If you try to leave the page with unsaved changes, Tellius asks whether to discard them.

{% hint style="info" %}
**Edit the YAML or ask Kaiya?** Edit the YAML for a small, exact change you already know how to write, such as a synonym or a description. Ask Kaiya in the chat for anything that depends on the data, such as a new join or metric, because Kaiya checks it against the data and runs draft checks before it saves.
{% endhint %}

### Versions

**Versions** lists every saved version with **Version**, **Saved by**, **Saved at**, **Name**, **Description** and **Actions**. The current version is marked **(current)**. A model with a single version shows **This model has one version; save a change to compare versions.**

To see what changed, select **Compare with current** on an earlier version. The comparison shows how many changes there are and lists the **Changes by section**: each table, relationship, metric, term, rule or analysis that was added, removed or changed, and which fields changed, with changed rows tinted. If two versions have the same content, the comparison says so. Below that, **YAML, side by side** shows both versions' YAML next to each other, with removed lines in red and added lines in green.

### Sharing a context model

Select **Share** in the model page's menu (three dots), or in the row menu in the list. In the **Share Context model** dialog:

1. Under **Share with**, type a first or last name, username, email or user group name.
2. Choose the access level: **Can view** or **Can Edit**. The Business View, datasets and datasources the model uses are shared along with it.
3. Select **Share**, or **Cancel** to close the dialog without sharing.

People you share with see the model under **Shared with me**. Anyone with **Can Edit** access can edit the model and approve, publish or reject suggestions, as long as their role has **Full Access** to **Context Models**. Sharing a model also needs **Full Access**. Only the owner or an admin can delete it.

### Archiving and deleting

* **Archive** hides a model from the main list without deleting it. Open the **Archived** tab to see it again, and select **Unarchive** to bring it back.
* **Delete** removes the model and all its versions, and conversations that used it no longer have it. This can't be undone. Only the model's owner or an admin can delete a model. Before deleting, Tellius checks what still uses the model. If Kaiya Missions, Kaiya Apps or conversations depend on it, the dialog lists them under **This model is still in use**. Those Missions and Apps are kept but lose their data source, so published Missions fail on their next run and Apps stop refreshing. To delete anyway, you must confirm that you understand this.

{% hint style="warning" %}
**Archive rather than delete** when you only want to stop people from picking a model. Missions and Apps that still use a deleted model can no longer get their data.
{% 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/exploring-and-editing-a-context-model.md?ask=<question>&goal=<user_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.