ElasticsearchHybridRetriever

Retrieve documents from an ElasticsearchDocumentStore using a combination of BM25 keyword search and dense vector similarity search.

Key Features

• Hybrid retrieval that combines BM25 keyword search with embedding-based vector search.
• Uses Reciprocal Rank Fusion (RRF) by default to merge results from both search methods.
• Configurable join modes for result merging.
• Built-in text embedder for automatic query embedding.
• Separate top_k and filter settings for BM25 and embedding sub-retrievers.

Configuration

1. Drag the ElasticsearchHybridRetriever component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   • Configure the ElasticsearchDocumentStore with your Elasticsearch instance details.
   • Set the embedder to the text embedder for query embedding.
   • Set top_k to control the final number of documents to return.
4. Go to the Advanced tab to configure top_k_bm25, top_k_embedding, fuzziness, join_mode, and filter policies.

Connections

ElasticsearchHybridRetriever receives the user query as a text string, typically from the Input component. It outputs a merged list of documents combining keyword and semantic search results.

Source Code

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

Usage Examples

Basic Configuration

  ElasticsearchHybridRetriever:
    type: haystack_integrations.components.retrievers.elasticsearch.elasticsearch_hybrid_retriever.ElasticsearchHybridRetriever
    init_parameters:
      top_k: 10
      document_store:
        type: haystack_integrations.document_stores.elasticsearch.document_store.ElasticsearchDocumentStore
        init_parameters:
          hosts:
          - http://localhost:9200
          index: my-index
      embedder:
        type: haystack.components.embedders.openai_text_embedder.OpenAITextEmbedder
        init_parameters:
          model: text-embedding-3-small

Parameters

Inputs

Parameter	Type	Description
query	str	The text query for both keyword and embedding-based search.
filters_bm25	Optional[Dict[str, Any]]	Filters to apply to the BM25 keyword retriever.
filters_embedding	Optional[Dict[str, Any]]	Filters to apply to the embedding retriever.
top_k_bm25	Optional[int]	The maximum number of documents from the BM25 retriever.
top_k_embedding	Optional[int]	The maximum number of documents from the embedding retriever.

Outputs

Parameter	Type	Description
documents	List[Document]	The merged and reranked retrieved documents.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
document_store	ElasticsearchDocumentStore		An instance of ElasticsearchDocumentStore.
embedder	TextEmbedder	(required)	A text embedder component for converting the query to a vector.
filters_bm25	Optional[Dict[str, Any]]	None	Default filters for the BM25 sub-retriever.
fuzziness	str	"AUTO"	Fuzziness setting for BM25 keyword matching.
top_k_bm25	int	10	Maximum number of results from the BM25 retriever.
scale_score	bool	False	Whether to scale BM25 scores to the 0-1 range.
filter_policy_bm25	Union[str, FilterPolicy]	FilterPolicy.REPLACE	Filter policy for the BM25 sub-retriever.
filters_embedding	Optional[Dict[str, Any]]	None	Default filters for the embedding sub-retriever.
top_k_embedding	int	10	Maximum number of results from the embedding retriever.
num_candidates	Optional[int]	None	The number of candidates to consider before final ranking for embedding retrieval.
filter_policy_embedding	Union[str, FilterPolicy]	FilterPolicy.REPLACE	Filter policy for the embedding sub-retriever.
join_mode	Union[str, JoinMode]	JoinMode.RECIPROCAL_RANK_FUSION	The method for merging results from both retrievers.
weights	Optional[List[float]]	None	Weights for each retriever when using weighted join modes.
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 for both retrieval methods.
filters_bm25	Optional[Dict[str, Any]]	None	Filters to apply at query time for the BM25 retriever.
filters_embedding	Optional[Dict[str, Any]]	None	Filters to apply at query time for the embedding retriever.
top_k_bm25	Optional[int]	None	Override the init-time top_k_bm25 setting.
top_k_embedding	Optional[int]	None	Override the init-time top_k_embedding setting.

Related Information

• ElasticsearchBM25Retriever
• ElasticsearchEmbeddingRetriever
• Pipeline Components