Skip to main content
A retriever is a named search configuration on a knowledge base. It decides how an end user’s question finds the right passages, how much surrounding context each match keeps, and how many results reach the agent. Every question follows the same path through a retriever, and each stage of that path is a setting you can change.
A question moves through the query transform, the search strategy, the results-to-retrieve cap, the re-rank refinement and the results-to-keep limit before reaching the agent.

​
Many retrievers, one live default

A knowledge base can hold several retrievers side by side. The retriever carrying the Default badge is the live default, and it answers every live query. The other retrievers exist to be compared. You can test any indexed retriever, run it in an experiment, and promote it with Make default from its card menu. Promotion swaps the live default without rebuilding anything. Configure a retriever describes the Retriever tab, its cards, and every notice it can show.

​
Presets and the custom path

Add retriever opens a picker with three ready-made presets, one per search strategy. The picker recommends Vector search as the right first choice for most agents.
The Add a retriever picker with the Vector search, Keyword + vector blend, Keyword / exact terms and Custom retriever cards
The fourth card, Custom retriever, opens the Build from scratch dialog. There you choose the index, the chunking, the embedding model, the query transform, the search strategy, and the refinement yourself. The rest of this page explains what those choices mean.

​
Search strategies

The Search setting picks how a retriever matches text. The meaning-based strategies read the Embedding model setting. OpenAI · 3-small is the default. The two Cohere models show Not available right now when the Cohere provider is unavailable.

​
Query transforms

A retriever can transform the question before it searches. The Query setting selects the transform, and each option carries a short description.

​
Chunking and parent context

Documents are split into chunks before indexing, and the Index setting controls how. Two options ship today. Contextual chunks and Summary index appear disabled as “(coming soon)”. Standard chunks cuts documents into fixed-size pieces, with an overlap so sentences are not cut at the boundaries. Parent-child indexes small child chunks for precise matching. At answer time, each matched child is swapped for its larger parent, so the agent receives the wider section around the match. Long documents keep their context this way.
A side-by-side contrast of standard chunking into fixed-size pieces with overlap and parent-child chunking where small indexed children are swapped for their larger parents.

​
Re-ranking and result limits

Results to retrieve caps how many passages reach the agent for each question. More passages give the agent more to work with but cost more tokens. The Refinement setting adds an optional second pass. Choose Re-rank top results to reorder a wider set of passages with a more accurate model. The Passages to re-rank field sets the size of that wider set. The Results to retrieve field keeps only the best of them. When the count is still at its default of 5, choosing re-ranking raises it to 20, since re-ranking works best with a wider net. Re-ranking requires the Cohere provider and trades a little latency for cleaner input to the agent.

​
Indexes and serving

A retriever stays out of the agent’s Knowledge tool until its first index build finishes, and you cannot test or compare it before then.
How a retriever index moves between Not indexed, Indexing, Ready, Needs reindex, Updating index and Error
Retrievers with the same indexing settings can share one index. When a knowledge base has several retrievers, each card shows an index letter, such as Index A. Retrievers with the same letter share one index, and reindexing any of them rebuilds it for all. Changing a setting under How it’s indexed rebuilds the index, and the retriever keeps answering from the old one until the new one is ready. A stale retriever never goes silent. When documents change after a build, the retriever keeps answering from the index it already has. The amber “needs reindexing” alerts exist to tell you that live answers are behind your documents. Each card carries an Auto or Manual badge for its reindex mode. With Auto, a scheduled crawl starts the reindex, while your manual edits always wait for a reindex you start. While any retriever is building its index, the knowledge base locks document changes with the tooltip Locked while a retriever is building. See Manage documents for the reindex flow.

​
Testing a retriever by hand

Test retriever in a card’s menu opens a dialog that searches that one retriever and shows which chunks it retrieves. For the steps, see The Test retriever dialog. Each result under Top results carries a Score badge that ranks chunks within this retriever only. Each search strategy scores on its own scale, so scores are not comparable across retrievers.

​
Measuring retrieval quality

Hand testing shows single answers, while the Dataset and Experiments tabs measure quality across many questions at once.

​
Deleting is reversible

A deleted retriever moves to Recently deleted for 30 days and normally keeps its index, so a restored retriever answers again without a reindex. If its index data is gone, the restore message asks you to reindex it. After 30 days the index is removed with it. Organization admins can also purge one immediately with Delete forever. The last indexed retriever of a knowledge base cannot be deleted. Index another retriever first.