# Indexing Best Practices

How Risotto indexes and searches your knowledge sources, and how to choose and maintain indexes that give good answers

Risotto can answer common questions in Slack or Microsoft Teams from your company's own content, such as Confluence spaces, Notion pages, Google Drive folders and Slack threads. Before it can, it needs to index those sources. You create and manage indexes in **Knowledge > Indexes** or on the **Knowledge** tab of each integration's page: see [Indexes](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes).

## Start small

Think of Risotto as an eager new intern: motivated to help but unfamiliar with your organization. Instead of pointing them at your entire Google Drive and asking them to figure it out, you would guide them to a few key documents. Start the same way with Risotto: index a small set of good documents, and add more as you find questions it can't answer well.

## Don't index everything

This is the most important tip for new Risotto users. It's tempting to index everything, but being selective works better, for two reasons:

1. **Answer quality.** Too much content adds noise, and makes it harder for Risotto to find the right passage.
2. **Freshness.** A small, high-quality index is quick to reindex, so you can keep it current.

## How indexing works

When you create an index, an indexing job reads the source through its API, with the credentials you gave for that source. Then, for each document, Risotto:

1. **Splits it into passages.** A documentation page or an article is split sentence by sentence, and each sentence keeps the sentences around it, so a match comes back with its context. Slack threads and Jira issues are split into larger chunks.
2. **Computes an embedding for each passage.** An embedding is a list of numbers that represents what the passage means, so a search can find it even when the words differ. Risotto computes it with an embedding model on AWS Bedrock.
3. **Stores the passages** in your organization's own table in Risotto's search database. Each passage keeps its text for keyword search, its embedding for semantic search, and the labels that decide who can get answers from it: its source, and the index's department, audience and profile filters.

*Product example: Diagram: Risotto reads a source, splits each document into passages, computes an embedding for each passage and stores it in the organization's table.*

Risotto indexes a document whole or not at all. A document over the size limits is skipped and your admins are notified: see [Document size limits](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes#document-size-limits).

When you delete an index, Risotto deletes its passages from the search database. Add, reindex and delete indexes as often as you need to keep your content fresh.

## How Risotto searches your knowledge

The search uses both keywords and meaning. When the agent looks for an answer:

1. The agent writes a search query from the request. It does not always search with the exact words of the ticket. For a short, clear question, Risotto uses the question as it is.
2. Risotto keeps only the passages that this ticket may use. See [What a ticket can find](#what-a-ticket-can-find).
3. Risotto matches the query against two groups of passages at the same time, by keyword and by meaning. In documentation and articles, the keyword match counts for more. In Slack threads and tickets, the meaning counts for more. At most two Slack threads and two Jira issues go on to the next step.
4. Risotto scores each result again for relevance to the query and drops weak matches. Articles get the most weight, then documentation pages such as Confluence, Notion and Google Drive, then Slack threads and tickets.
5. If the results are weak, Risotto also searches other wordings of the query and combines the results.

*Product example: Diagram: a knowledge search filters to what the ticket may use, matches documentation and conversations by keyword and meaning, reranks, and retries other wordings when results are weak.*

If no passage passes, the agent has no source to answer from.

When [Slack AI search](https://www.tryrisotto.com/docs/dashboard/knowledge/connect) is on, the Slack results come live from Slack's own search instead of from your Slack indexes.

### What a ticket can find

A page can only be found if it is in an index that this ticket can use:

- The **Department** and **Audience** settings of an index are strict limits. A ticket searches the organization-wide indexes and the indexes of its own department. A ticket in a sub-department searches its parent department's indexes. See [Indexes](https://www.tryrisotto.com/docs/dashboard/knowledge/indexes#configuration).
- **Profile filters** narrow the results to documents meant for the requestor, for example by location or role.
- A runbook can limit a search to some indexes, or exclude some, with a [knowledge directive](https://www.tryrisotto.com/docs/dashboard/runbooks).
- A Slack thread is searched only when its last reply is less than 90 days old.
- A page outside the indexed space or folder, or excluded by the index's **Query** filter, is not indexed.
- A page that the account Risotto uses to read your source cannot open is not indexed.

To help the search find an article, use the words your requestors use in their requests, in the title and in the text.

## How Risotto answers from a document

Risotto does not paste the page into the chat. It reads the pages the search returns, writes a short answer to the specific question, and cites the page with a link, so the requestor can open the full document.

Before it sends, Risotto checks the draft against the cited page. If the page answers only part of the request, Risotto escalates the ticket to your team instead of sending a partial answer. When a request often has two parts (for example, "the preloaded backgrounds are missing, and I cannot upload a new one"), cover both parts in one article, and the same request passes next time.

Formatting from the source carries over only as far as Slack can show it:

- Headings come through as bold text.
- Bulleted and numbered lists render as lists.
- Tables have no Slack rendering. Risotto turns a table into prose or lists only part of it. A list carries the same information more reliably than a table.

## Tips for improving response quality

A few high-quality indexes usually outperform a large number of low-quality sources. These tips help Risotto answer better:

1. **Turn good Slack threads into articles** (Slack only). Add the ✍️ (`:writing_hand:`) reaction to a thread to create an [article](https://www.tryrisotto.com/docs/dashboard/knowledge/articles#automating-article-creation-in-slack) from it. Articles get the most weight in the search, so this is your main tool for refining Risotto's answers.
2. **Rate answers.** When Risotto asks for feedback under an answer in Slack, click ⭐, 👍 or 👎. After a 👎, Risotto asks you in a direct message what went wrong. The Risotto team uses this feedback to improve the system.
3. **Reindex after important changes.** Articles are reindexed each time you save them, and Slack channel indexes update automatically. Confluence updates in real time when you use the Confluence app. For other sources, reindex from **Knowledge > Indexes**: open the row's **⋮** menu and click **Reindex**.
4. **Remove inaccurate sources.** If Risotto gives wrong answers, update the content at its source and reindex, which keeps your knowledge current. You can also delete the index and index a more accurate source instead. To stop Risotto from using a Slack thread, add the ⏏️ (`:eject:`) reaction to it (Slack only). See [Slack reactions](https://www.tryrisotto.com/docs/operating/slack-emojis).

Source: https://www.tryrisotto.com/docs/concepts/indexing
