SolrBM25Retriever

Retrieve documents from a SolrDocumentStore using Solr's BM25 similarity for keyword-based search.

Key Features

• Performs keyword search using Solr's BM25 ranking algorithm.
• Supports fuzzy matching with configurable per-term edit distance.
• Optionally scales BM25 scores into the (0, 1) range.
• Supports requiring all query terms to match for stricter retrieval.
• Configurable filter policy to merge or replace filters at query time.

Configuration

1. Drag the SolrBM25Retriever component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. Configure the nested SolrDocumentStore with your Solr connection details:
   • Set url to your Solr base URL (defaults to http://localhost:8983/solr).
   • Set core to the name of your Solr core or SolrCloud collection.
   • Set auth credentials as secrets called SOLR_USERNAME and SOLR_PASSWORD. For instructions, see Add Secrets.
4. Set top_k, fuzziness, and other retrieval parameters on the Advanced tab.

Connections

SolrBM25Retriever receives a query string at runtime. It outputs a list of Document objects that you can connect to a PromptBuilder or other downstream components.

Source Code

To check this component's source code, open bm25_retriever.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  SolrBM25Retriever:
    type: haystack_integrations.components.retrievers.solr.bm25_retriever.SolrBM25Retriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.solr.document_store.SolrDocumentStore
        init_parameters:
          url: http://localhost:8983/solr
          core: haystack
      top_k: 10
      fuzziness: 0

Using the Component in a Pipeline

# haystack-pipeline
components:
  document_store:
    type: haystack_integrations.document_stores.solr.document_store.SolrDocumentStore
    init_parameters:
      url: http://localhost:8983/solr
      core: haystack
      auth:
      - type: env_var
        env_vars:
        - SOLR_USERNAME
        strict: false
      - type: env_var
        env_vars:
        - SOLR_PASSWORD
        strict: false

  retriever:
    type: haystack_integrations.components.retrievers.solr.bm25_retriever.SolrBM25Retriever
    init_parameters:
      document_store: document_store
      top_k: 10
      fuzziness: 0
      scale_score: false
      all_terms_must_match: false

connections: []

inputs:
  query:
  - retriever.query

outputs:
  documents: retriever.documents

Parameters

Inputs

Parameter	Type	Description
query	str	The query string to search for.
filters	Optional[Dict[str, Any]]	Filters to apply at query time.
top_k	Optional[int]	Maximum number of documents to retrieve. Overrides the init-time value.
fuzziness	Optional[int]	Per-term edit distance for fuzzy matching.
scale_score	Optional[bool]	Whether to scale BM25 scores into the (0, 1) range.
all_terms_must_match	Optional[bool]	Whether every query term must match.

Outputs

Parameter	Type	Description
documents	List[Document]	A list of matching documents, most relevant first.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
document_store	SolrDocumentStore		The Solr document store to search.
filters	Optional[Dict[str, Any]]	None	Default filters applied to all searches.
fuzziness	int	0	Per-term edit distance. 0 disables fuzzy matching.
top_k	int	10	Maximum number of documents to return.
scale_score	bool	False	Whether to scale scores into the (0, 1) range.
all_terms_must_match	bool	False	Whether every query term must match.
filter_policy	FilterPolicy	FilterPolicy.REPLACE	How to handle filters passed at query time. REPLACE replaces init-time filters; MERGE combines them.
raise_on_failure	bool	True	Whether a failing search raises an exception or logs and returns no documents.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
query	str		The search query string.
filters	Optional[Dict[str, Any]]	None	Runtime filters to apply.
top_k	Optional[int]	None	Maximum number of documents to retrieve. Overrides the init-time value.
fuzziness	Optional[int]	None	Per-term edit distance. Overrides the init-time value.
scale_score	Optional[bool]	None	Whether to scale scores. Overrides the init-time value.
all_terms_must_match	Optional[bool]	None	Whether every term must match. Overrides the init-time value.

Related Information

• SolrEmbeddingRetriever
• Add Secrets
• Pipeline Components