Skip to content
Nappai Documentation

BM25 Retriever

BM25 Retriever finds, among the documents of a vector database, those containing the words of the question, giving more weight to uncommon words. It complements search by meaning when exact terms matter, such as a product code or a proper name.

Upper or lower case, accents and punctuation do not matter: “jt-777?” finds “JT-777:”, and codes with dashes are matched whole. It reads every document of the database (with FAISS, Chroma and Qdrant; with other databases, up to 10,000).

A retriever receives a question and returns the document pieces that best answer it, so an agent or model can reply with your information.

When to use it

  • Your users search by references, codes or exact names.
  • You want to combine word search with search by meaning in an Ensemble Retriever.
  • Search by meaning returns similar results but not the exact document.

Configuration

FieldWhat it does
Search QueryThe question or words to search for.
Vector Store (required)The connector where you plug the Vector Store output of a vector database holding the documents.
Number of ResultsHow many documents it returns. Default: 5.

The same data, no extra preparation

No. It uses the same chunks you already stored in the vector database, as they are, with no second ingestion or other format: on every run it reads them from the database (all of them in FAISS, Chroma and Qdrant; up to 10,000 in the others) and builds its keyword index there and then. If you chunked with Contextual Text Splitter, it also searches each chunk’s context sentence. The only thing to watch is volume: with very large collections, reading them on every question takes longer.

Output

  • Retriever: the search engine, to connect to components that ask for one, such as another in this family or a question-answering component.
  • Results: the pieces found for Search Query, best first, each with its document’s data and its position in rank. Pass them to a prompt or an agent.

If the database cannot be read or has no documents, the component stops with an error that says so, instead of returning an empty result.

Use as an agent tool

Connect BM25 Retriever to the Tools input of an Agent and the agent searches on its own: it writes Search Query with the words or codes to look for. It is called keyword_search by default; in the Tool tab change the description to say what your documents contain.

Example

A hardware shop wants its assistant to find products by reference.

  1. Connect the Vector Store output of its product database to Vector Store.
  2. Connect the customer’s question, for example “REF-4521”, to Search Query.
  3. Pass Results to the agent.

Measured figures

Measured on 17 October 2026 on a test knowledge base (9 documents of a fictional repair service, 40 questions). It is a single synthetic set: it shows how the technique behaves, not a promise for your data.

  • For questions about an exact code or reference, the right result was in the top 5 in 88 % of cases.
  • Combined in equal parts with search by meaning in an Ensemble Retriever, it got every code question right (in the top 5) and 83 % overall.
  • On its own, by words, it falls short on questions phrased with other words: use it together with a search by meaning.

Video

This video compares plain search with hybrid search plus reranking, on a question about a part reference.

What you see in the video:

  1. Qdrant alone, with its top 5 results, misses part VL-2210.
  2. BM25 Retriever and Qdrant joined in Ensemble Retriever with Weights 0.5, 0.5, followed by Local Rerank: it asks for 20 candidates and keeps the best 5.
  3. The first result is the spare parts list of the Vellani Aurora manual, where “VL-2210: PT1000 temperature probe” appears, with a relevance of 0.56.
  4. The same combination, connected as an Agent tool, answers the question correctly.

To see when to combine words and meaning, see Search techniques in the RAG guide.