OpenSearchHybridRetriever

Retrieve documents from an OpenSearchDocumentStore using hybrid search, combining BM25 keyword-based retrieval with dense embedding retrieval. Use this super-component in query pipelines to get the benefits of both lexical and semantic search.

Embedding Models in Query Pipelines and Indexes

The embedding model you use to embed documents in your indexing pipeline must be the same as the embedding model you use to embed the query in your query pipeline.

This means the embedders for your indexing and query pipelines must match. For example, if you use CohereDocumentEmbedder to embed your documents, you should use CohereTextEmbedder with the same model to embed your queries.

Key Features

• Combines BM25 keyword search and embedding-based vector search in a single component.
• Uses Reciprocal Rank Fusion (RRF) by default to merge results, with configurable join modes and weights.
• Exposes separate top_k and filter settings for each retrieval method.
• Built as a Haystack super_component — wraps an internal pipeline with OpenSearchBM25Retriever, a text embedder, OpenSearchEmbeddingRetriever, and a DocumentJoiner.

Configuration

Add Workspace-Level Integration

1. Click your profile icon and choose Settings.
2. Go to Workspace>Integrations.
3. Find the provider you want to connect and click Connect next to them.
4. Enter the API key and any other required details.
5. Click Connect. You can use this integration in pipelines and indexes in the current workspace.

Add Organization-Level Integration

1. Click your profile icon and choose Settings.
2. Go to Organization>Integrations.
3. Find the provider you want to connect and click Connect next to them.
4. Enter the API key and any other required details.
5. Click Connect. You can use this integration in pipelines and indexes in all workspaces in the current organization.

1. First, configure an OpenSearchDocumentStore with both BM25 and embedding support.
2. Drag the OpenSearchHybridRetriever component onto the canvas from the Component Library.
3. Set the embedder parameter to a text embedder component (for example, SentenceTransformersTextEmbedder).
4. Adjust top_k_bm25 and top_k_embedding to control how many candidates each retriever returns before merging.

Connections

OpenSearchHybridRetriever receives a text query string as input. It outputs a list of Document objects merged from both BM25 and embedding results.

Source Code

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

Usage Examples

Basic Configuration

  OpenSearchHybridRetriever:
    type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
    init_parameters:
      document_store: OpenSearchDocumentStore
      embedder:
        type: haystack_integrations.components.embedders.sentence_transformers.sentence_transformers_text_embedder.SentenceTransformersTextEmbedder
        init_parameters:
          model: sentence-transformers/all-MiniLM-L6-v2
      top_k_bm25: 10
      top_k_embedding: 10
      join_mode: reciprocal_rank_fusion

Parameters

Inputs

Parameter	Type	Description
query	str	The text query to search for.
filters_bm25	Optional[Dict[str, Any]]	Filters to apply to the BM25 retriever.
filters_embedding	Optional[Dict[str, Any]]	Filters to apply to the embedding retriever.
top_k_bm25	Optional[int]	Maximum number of BM25 results to return. Overrides the init-time value.
top_k_embedding	Optional[int]	Maximum number of embedding results to return. Overrides the init-time value.

Outputs

Parameter	Type	Description
documents	List[Document]	A merged list of documents from both BM25 and embedding retrieval.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
document_store	OpenSearchDocumentStore		The OpenSearch document store to retrieve documents from.
embedder	TextEmbedder		A text embedder component used to embed the query for vector search.
filters_bm25	Optional[Dict[str, Any]]	None	Default filters to apply to BM25 retrieval.
fuzziness	int or str	0	Fuzziness setting for BM25 keyword matching.
top_k_bm25	int	10	Maximum number of BM25 candidates to retrieve.
scale_score	bool	False	Whether to scale BM25 scores to a [0, 1] range.
all_terms_must_match	bool	False	Whether all query terms must appear in a document for BM25 matching.
filter_policy_bm25	FilterPolicy	FilterPolicy.REPLACE	Filter policy for BM25 retrieval.
custom_query_bm25	Optional[Dict[str, Any]]	None	A custom OpenSearch query for BM25 retrieval.
filters_embedding	Optional[Dict[str, Any]]	None	Default filters to apply to embedding retrieval.
top_k_embedding	int	10	Maximum number of embedding candidates to retrieve.
filter_policy_embedding	FilterPolicy	FilterPolicy.REPLACE	Filter policy for embedding retrieval.
custom_query_embedding	Optional[Dict[str, Any]]	None	A custom OpenSearch query for embedding retrieval.
join_mode	JoinMode	JoinMode.RECIPROCAL_RANK_FUSION	How to merge results from BM25 and embedding retrievers.
weights	Optional[List[float]]	None	Weights for each retriever when merging results.
top_k	Optional[int]	None	Maximum number of documents to return after merging.
sort_by_score	bool	True	Whether to sort merged results by score.

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 text query to search for.
filters_bm25	Optional[Dict[str, Any]]	None	Runtime filters for BM25 retrieval.
filters_embedding	Optional[Dict[str, Any]]	None	Runtime filters for embedding retrieval.
top_k_bm25	Optional[int]	None	Maximum BM25 results. Overrides the init-time value.
top_k_embedding	Optional[int]	None	Maximum embedding results. Overrides the init-time value.

Related Information

• OpenSearchBM25Retriever
• OpenSearchEmbeddingRetriever
• Pipeline Components