> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/files-knowledge-and-retrieval/retrieval-settings-and-result-ranking.md).

# Retrieval Settings and Result Ranking

Retrieval settings control how a query finds and selects source passages. Choose a search strategy for the type of question and inspect the returned evidence before generating an answer.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2Fj3F04vpioCvuNyF6V1PS%2FG043.mp4?alt=media&token=9bea87bf-0e03-4f26-b85f-503611ebffd3>" %}

## Before you begin

Indexed content and access to the query or retrieval settings.

## Search and ranking concepts

| Term            | Definition                                                                                                                                    |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Semantic search | Retrieval based on similarity of meaning. Useful when the query and source use different wording.                                             |
| Keyword search  | Retrieval based on terms in the query and source. Useful for exact names, identifiers, and specialized terms.                                 |
| Hybrid search   | Retrieval that combines semantic and keyword approaches. Useful when both meaning and exact terms matter.                                     |
| Ranking         | The ordering of eligible results by the selected retrieval method. A high position or score is not proof that a passage answers the question. |

## Configuration options

| Option | Purpose                                    | Behavior                                                           |
| ------ | ------------------------------------------ | ------------------------------------------------------------------ |
| Top K  | The requested number of retrieval results. | More results can add evidence and irrelevant or repeated passages. |

## Configure retrieval

1. Choose semantic, keyword, or hybrid search where the selected interface supports it.
2. Set the number of results and submit the query.
3. Inspect relevance, source coverage, and repeated passages before changing the settings.

![Inspect the returned passage and its source to determine whether retrieval found the right evidence.](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/W4E73dbXbrq0uTbJsUXO/assets/g043-g043-01-baseline.png)

Inspect the returned passage and its source to determine whether retrieval found the right evidence.

The response contains source evidence relevant to the question.

## Behavior and limitations

The public v2 query contract accepts top\_k from 1 to 20. It uses the field strategy; MCP kb\_search uses query\_strategy. More results can increase context and irrelevant material. A relevance score is not a guarantee that a passage answers the question.

| Strategy | Useful for                                        |
| -------- | ------------------------------------------------- |
| Semantic | Similar meaning even when wording differs.        |
| Keyword  | Exact terms, names, or identifiers.               |
| Hybrid   | Questions that need both meaning and exact terms. |

## Related resources

[Evaluate retrieval](https://docs.stackai.com/guides-and-quickstarts/knowledge-and-retrieval/evaluate-retrieval.md)

[File Inputs, Supported Formats, and Size Limits](https://docs.stackai.com/technical-reference/files-knowledge-and-retrieval/file-inputs-supported-formats-and-size-limits.md)


---

# 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://docs.stackai.com/technical-reference/files-knowledge-and-retrieval/retrieval-settings-and-result-ranking.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.
