> 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/stackai-tools/knowledge-base-access/search-knowledge-base.md).

# Search Knowledge Base

Retrieve relevant content from one or more StackAI knowledge bases. Use this tool to ground an answer in your organization’s documents.

## Use this tool

1. Select the knowledge bases or files to search in **Knowledge Base**. Ensure their content has finished processing.
2. Enter the question in **Query**. If using **Knowledge Base IDs**, supply IDs from [List Knowledge Bases](https://docs.stackai.com/stackai-tools/knowledge-base-access/list-knowledge-bases.md).
3. Start with the default search settings. Adjust **Top Results**, **Output Format**, or **Max Characters** if the returned content is insufficient.
4. Run the tool and inspect **Search Results** before using them to generate an answer.

## Behavior and limits

When Knowledge Base IDs and selected bases are both supplied, the tool searches their intersection. IDs do not expand the configured selection. **Enforce StackAI knowledge base permissions** requires a signed-in user with access to every selected base and applies StackAI file restrictions. Search results contain retrieved content; they are not the final answer. Top Results permits 0–100 results. Max Characters limits the returned text.

## Inputs

| Field                    | Parameter                  | Description                                                                                                                                        |
| ------------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Query (required)         | `query`                    | The query to search for                                                                                                                            |
| Knowledge Base IDs       | `knowledge_base_ids`       | IDs returned by List Knowledge Bases. When configured bases are also selected, only bases present in both selections are searched.                 |
| Output Format            | `retrieval`                | Defines what unit of content is retrieved from the knowledge base. Pick the smallest unit that gives enough context for the question.              |
| Query Strategy           | `query_strategy`           | Defines how the knowledge base is searched. Pick based on whether the query relies on meaning or on specific terms.                                |
| Metadata Filter Strategy | `metadata_filter_strategy` | Controls how strictly metadata filters (e.g. author, date, file name/type) extracted from the query are applied when searching the knowledge base. |
| Document priority rules  | `priority_metadata_filter` | Metadata rules that restrict and prioritize matching documents. See Document priority rules below.                                                 |
| Top Results              | `top_k`                    | Maximum number of results to return from the knowledge base, ordered by relevance. Allowed range: 0-100. Default: `10`.                            |

## Configuration

| Field                                      | Parameter                     | Description                                                                                                                                                                                                          |
| ------------------------------------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Knowledge Base (required)                  | `selected_kb_items`           | The selected items from the knowledge base to search in                                                                                                                                                              |
| Enforce StackAI knowledge base permissions | `enforce_end_user_kb_access`  | Use permissions configured in StackAI. The user must be signed in and have access to every selected knowledge base; StackAI file-level restrictions are also enforced before results are returned. Default: `false`. |
| Max Characters                             | `result_len`                  | Defines the maximum length of the result in characters. Default: `15000`.                                                                                                                                            |
| Answer Multiple Questions                  | `multi_query`                 | Enable to get the answer from multiple questions in parallel. Default: `false`.                                                                                                                                      |
| Advanced Q\&A                              | `advanced_rag`                | Enable to handle questions to compare documents or summarize documents. Default: `false`.                                                                                                                            |
| Rerank                                     | `rerank`                      | Reorder retrieved results to improve their relevance to the query. Default: `false`.                                                                                                                                 |
| Query Transformation                       | `enable_query_transformation` | Transform the query before retrieval to help find relevant content. Default: `false`.                                                                                                                                |
| Output Fields                              | `output_fields`               | Select which fields to include in the search result items. Leave empty to include every field.                                                                                                                       |

## Outputs

| Field          | Parameter        | Description                                                 |
| -------------- | ---------------- | ----------------------------------------------------------- |
| Query          | `query`          | The query that was used to search the knowledge base        |
| Search Results | `search_results` | The resulting chunks of text from the knowledge base search |

### Document priority rules

This setting accepts a JSON object or a variable that resolves to one. Documents must match a rule to be searched. Priority 1 ranks above priority 2. Within a priority, the tool accepts any matching condition; within a condition, all field requirements must match.

Supported comparisons are `eq`, `ne`, `contains`, `like`, `ilike`, `gt`, `lt`, `gte`, `lte`, and `exists`. `contains` ignores case; `like` is case-sensitive and `ilike` ignores case. Use `*` or `exists` to match documents that have a field.


---

# 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/stackai-tools/knowledge-base-access/search-knowledge-base.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.
