Implementation:Deepset ai Haystack InMemoryEmbeddingRetriever

Metadata

Field	Value
Implementation Name	InMemoryEmbeddingRetriever
Implementing Principle	Deepset_ai_Haystack_Embedding_Based_Retrieval
Class	InMemoryEmbeddingRetriever
Module	haystack.components.retrievers.in_memory.embedding_retriever
Source Reference	haystack/components/retrievers/in_memory/embedding_retriever.py:L13-238
Repository	Deepset_ai_Haystack
Dependencies	numpy (via InMemoryDocumentStore)

Overview

InMemoryEmbeddingRetriever is a Haystack component that retrieves documents from an InMemoryDocumentStore based on the semantic similarity between a query embedding and stored document embeddings. It receives a pre-computed query embedding vector and returns the top-k most similar documents, enabling semantic search over pre-embedded document collections.

Description

This retriever delegates similarity computation to the InMemoryDocumentStore.embedding_retrieval() method. The component itself does not perform any embedding; it expects a pre-computed query embedding as input (typically produced by a SentenceTransformersTextEmbedder earlier in the pipeline).

Key behaviors:

• Document store validation: The constructor enforces that the provided document store is an instance of InMemoryDocumentStore, raising a ValueError otherwise.
• Filter policy: Supports two filter policies via FilterPolicy:
  • REPLACE (default): Runtime filters completely override initialization filters.
  • MERGE: Runtime filters are merged with initialization filters.
• Score scaling: When scale_score=True, similarity scores are normalized to a 0-1 range.
• Embedding return control: The return_embedding parameter controls whether the document embeddings are included in the returned documents. Setting this to False (the default) reduces memory usage in downstream components.
• Top-k validation: The top_k parameter must be greater than 0.
• Async support: The component provides a run_async() method for asynchronous retrieval.

Code Reference

Import

from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever

Constructor Signature

InMemoryEmbeddingRetriever(
    document_store: InMemoryDocumentStore,
    filters: dict[str, Any] | None = None,
    top_k: int = 10,
    scale_score: bool = False,
    return_embedding: bool = False,
    filter_policy: FilterPolicy = FilterPolicy.REPLACE,
)

Parameter	Type	Default	Description
document_store	InMemoryDocumentStore	required	The document store to retrieve from. Must be an InMemoryDocumentStore instance.
filters	None	None	Default filters to narrow the search space.
top_k	int	10	Maximum number of documents to return.
scale_score	bool	False	When True, scales similarity scores to a 0-1 range.
return_embedding	bool	False	When True, includes document embeddings in the returned documents.
filter_policy	FilterPolicy	FilterPolicy.REPLACE	How runtime filters interact with init filters (REPLACE or MERGE).

I/O Contract

Input

Parameter	Type	Required	Description
query_embedding	list[float]	Yes	The embedding vector of the query to compare against document embeddings.
filters	None	No	Runtime filters to apply. Behavior depends on filter_policy.
top_k	None	No	Override the default maximum number of documents to return.
scale_score	None	No	Override the default score scaling behavior.
return_embedding	None	No	Override whether to return document embeddings.

Output

Key	Type	Description
documents	list[Document]	Documents ranked by embedding similarity, sorted from most to least similar.

The output dictionary has the structure:

{"documents": list[Document]}

Each returned Document has its score field populated with the similarity score. The embedding field is populated only when return_embedding=True.

Usage Examples

Basic Embedding Retrieval

from haystack import Document
from haystack.components.embedders import SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
from haystack.document_stores.in_memory import InMemoryDocumentStore

# Index documents with embeddings
docs = [
    Document(content="Python is a popular programming language"),
    Document(content="python ist eine beliebte Programmiersprache"),
]
doc_embedder = SentenceTransformersDocumentEmbedder()
doc_embedder.warm_up()
docs_with_embeddings = doc_embedder.run(docs)["documents"]

doc_store = InMemoryDocumentStore()
doc_store.write_documents(docs_with_embeddings)

# Retrieve using query embedding
retriever = InMemoryEmbeddingRetriever(doc_store)
text_embedder = SentenceTransformersTextEmbedder()
text_embedder.warm_up()
query_embedding = text_embedder.run("Programmiersprache")["embedding"]

result = retriever.run(query_embedding=query_embedding)
print(result["documents"])

In a Query Pipeline

from haystack import Pipeline
from haystack.components.embedders import SentenceTransformersTextEmbedder
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
from haystack.document_stores.in_memory import InMemoryDocumentStore

doc_store = InMemoryDocumentStore()
# (assume documents have been pre-embedded and written to doc_store)

pipeline = Pipeline()
pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
pipeline.add_component("retriever", InMemoryEmbeddingRetriever(
    document_store=doc_store,
    top_k=10,
    scale_score=True,
))
pipeline.connect("text_embedder.embedding", "retriever.query_embedding")

result = pipeline.run({"text_embedder": {"text": "What is semantic search?"}})
for doc in result["retriever"]["documents"]:
    print(f"{doc.content} (score: {doc.score:.4f})")

Retrieval with Metadata Filters

from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.document_stores.types import FilterPolicy

doc_store = InMemoryDocumentStore()
# (assume documents with metadata have been pre-embedded and written)

retriever = InMemoryEmbeddingRetriever(
    document_store=doc_store,
    top_k=5,
    filter_policy=FilterPolicy.MERGE,
    filters={"field": "meta.source", "operator": "==", "value": "wiki"},
)

# At runtime, merge additional filters
result = retriever.run(
    query_embedding=[0.1, 0.2, 0.3],  # pre-computed embedding
    filters={"field": "meta.language", "operator": "==", "value": "en"},
)

Related Pages

Implements Principle

• Principle:Deepset_ai_Haystack_Embedding_Based_Retrieval

• Principle: Deepset_ai_Haystack_Embedding_Based_Retrieval -- The principle that this component implements.
• Related Implementation: Deepset_ai_Haystack_SentenceTransformersTextEmbedder -- Text embedder that produces the query embedding consumed by this retriever.
• Related Implementation: Deepset_ai_Haystack_SentenceTransformersDocumentEmbedder -- Document embedder that produces the document embeddings stored in the document store.
• Related Implementation: Deepset_ai_Haystack_InMemoryBM25Retriever -- The keyword-based retriever for the same document store.
• Related Implementation: Deepset_ai_Haystack_TransformersSimilarityRanker -- Cross-encoder ranker often used to rerank embedding retrieval results.