OpenSearchEmbeddingRetriever

Retrieve documents from OpenSearchDocumentStore using vector similarity. The retriever compares the query embedding to stored document embeddings and returns the most semantically relevant documents.

Key Features

• Semantic retrieval using vector similarity (approximate kNN search).
• Requires document embeddings created by an indexing pipeline.
• Supports configurable filtering during approximate kNN search.
• Efficient filtering option for "faiss" and "lucene" kNN engines.
• Supports custom OpenSearch queries for advanced use cases.

Configuration

1. Drag the OpenSearchEmbeddingRetriever component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   • Set top_k to control the maximum number of documents to retrieve.
   • Optionally configure filters to narrow down the search space.
4. Go to the Advanced tab to configure filter_policy, custom_query, raise_on_failure, and efficient_filtering.

note

Make sure the embedding_dim of the OpenSearchDocumentStore matches the dimension of the embeddings created by your embedding model.

Connections

OpenSearchEmbeddingRetriever receives a query_embedding (a list of floats) from a text embedder such as SentenceTransformersTextEmbedder. Connect a text embedder's embedding output to the retriever's query_embedding input. The retriever outputs a documents list that you can send to a PromptBuilder, Ranker, or DocumentJoiner.

Source Code

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

Usage Examples

Basic Configuration

  OpenSearchEmbeddingRetriever:
    type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          index: ''
          max_chunk_bytes: 104857600
          embedding_dim: 384
          return_embedding: false
          create_index: true
          similarity: cosine
      top_k: 10
      filter_policy: replace
      raise_on_failure: true
      efficient_filtering: true

Using the Component in a Pipeline

This is an example of a semantic search pipeline where OpenSearchEmbeddingRetriever receives the query embedding from a text embedder and retrieves matching documents.

components:
  text_embedder:
    type: haystack.components.embedders.sentence_transformers_text_embedder.SentenceTransformersTextEmbedder
    init_parameters:
      model: sentence-transformers/all-MiniLM-L6-v2
      device:
      token:
      prefix: ''
      suffix: ''
      batch_size: 32
      progress_bar: true
      normalize_embeddings: false
      trust_remote_code: false
  OpenSearchEmbeddingRetriever:
    type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
          index: ''
          max_chunk_bytes: 104857600
          embedding_dim: 384
          return_embedding: false
          method:
          mappings:
          settings:
          create_index: true
          http_auth:
          use_ssl:
          verify_certs:
          timeout:
          similarity: cosine
      filters:
      top_k: 10
      filter_policy: replace
      custom_query:
      raise_on_failure: true
      efficient_filtering: true

connections:
- sender: text_embedder.embedding
  receiver: OpenSearchEmbeddingRetriever.query_embedding

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - text_embedder.text
  filters:
  - OpenSearchEmbeddingRetriever.filters

outputs:
  documents: OpenSearchEmbeddingRetriever.documents

Using in a RAG Pipeline

This example shows a RAG pipeline that uses OpenSearchEmbeddingRetriever to find relevant documents, then passes them to a generator to answer a question.

components:
  text_embedder:
    type: haystack.components.embedders.sentence_transformers_text_embedder.SentenceTransformersTextEmbedder
    init_parameters:
      model: sentence-transformers/all-MiniLM-L6-v2
      device:
      token:
      prefix: ''
      suffix: ''
      batch_size: 32
      progress_bar: true
      normalize_embeddings: false
      trust_remote_code: false
  retriever:
    type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
    init_parameters:
      document_store:
        type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
        init_parameters:
          hosts:
          index: ''
          max_chunk_bytes: 104857600
          embedding_dim: 384
          return_embedding: false
          method:
          mappings:
          settings:
          create_index: true
          http_auth:
          use_ssl:
          verify_certs:
          timeout:
          similarity: cosine
      filters:
      top_k: 10
      filter_policy: replace
      custom_query:
      raise_on_failure: true
      efficient_filtering: true
  prompt_builder:
    type: haystack.components.builders.prompt_builder.PromptBuilder
    init_parameters:
      required_variables: "*"
      template: |-
        Given the following documents, answer the question.

        Documents:
        {% for document in documents %}
        {{ document.content }}
        {% endfor %}

        Question: {{ question }}
        Answer:
  generator:
    type: haystack.components.generators.openai.OpenAIGenerator
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - OPENAI_API_KEY
        strict: true
      model: gpt-4o-mini
      generation_kwargs:
  answer_builder:
    type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
    init_parameters:
      reference_pattern: acm

connections:
- sender: text_embedder.embedding
  receiver: retriever.query_embedding
- sender: retriever.documents
  receiver: prompt_builder.documents
- sender: prompt_builder.prompt
  receiver: generator.prompt
- sender: generator.replies
  receiver: answer_builder.replies
- sender: retriever.documents
  receiver: answer_builder.documents
- sender: prompt_builder.prompt
  receiver: answer_builder.prompt

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - text_embedder.text
  - prompt_builder.question
  - answer_builder.query
  filters:
  - retriever.filters

outputs:
  documents: retriever.documents
  answers: answer_builder.answers

Parameters

Inputs

Parameter	Type	Default	Description
query_embedding	List[float]		Embedding of the query.
filters	Optional[Dict[str, Any]]	None	Filters applied when fetching documents. Filters are applied during the approximate kNN search to ensure the retriever returns top_k matching documents. The way runtime filters are applied depends on the filter_policy at initialization.
top_k	Optional[int]	None	Maximum number of documents to return.
custom_query	Optional[Dict[str, Any]]	None	A custom OpenSearch query containing a mandatory $query_embedding and an optional $filters placeholder.
efficient_filtering	Optional[bool]	None	If True, the filter is applied during the approximate kNN search. Only supported for knn engines "faiss" and "lucene".

Outputs

Parameter	Type	Default	Description
documents	List[Document]		List of documents similar to the query embedding.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
document_store	OpenSearchDocumentStore		An instance of OpenSearchDocumentStore to use with the retriever.
filters	Optional[Dict[str, Any]]	None	Filters applied when fetching documents from the document store.
top_k	int	10	Maximum number of documents to return.
filter_policy	Union[str, FilterPolicy]	FilterPolicy.REPLACE	Policy to determine how filters are applied. Possible options: merge — runtime filters are merged with initialization filters; replace — runtime filters replace initialization filters.
custom_query	Optional[Dict[str, Any]]	None	The custom OpenSearch query containing a mandatory $query_embedding and an optional $filters placeholder.
raise_on_failure	bool	True	If True, raises an exception if the API call fails. If False, logs a warning and returns an empty list.
efficient_filtering	bool	False	If True, the filter is applied during the approximate kNN search. Only supported for knn engines "faiss" and "lucene", not the default "nmslib".

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_embedding	List[float]		Embedding of the query.
filters	Optional[Dict[str, Any]]	None	Filters applied when fetching documents. The way runtime filters are applied depends on the filter_policy set during initialization.
top_k	Optional[int]	None	Maximum number of documents to return.
custom_query	Optional[Dict[str, Any]]	None	A custom OpenSearch query containing a mandatory $query_embedding and an optional $filters placeholder.
efficient_filtering	Optional[bool]	None	If True, the filter is applied during the approximate kNN search. Only supported for knn engines "faiss" and "lucene".

Related Information

• OpenSearchBM25Retriever
• OpenSearchHybridRetriever
• SentenceTransformersTextEmbedder