WeaviateHybridRetriever

Retrieve documents from a WeaviateDocumentStore using Weaviate's native hybrid search, which combines BM25 keyword matching with dense vector search. Use this component in query pipelines to benefit from both lexical and semantic retrieval.

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

• Uses Weaviate's built-in hybrid search API for seamless BM25 + vector fusion.
• Configurable alpha parameter to blend between keyword and vector search.
• Optionally filter results by maximum vector distance.
• Supports async execution via run_async.
• Configurable filter policy to merge or replace filters at query time.

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 a WeaviateDocumentStore in your pipeline.
2. Drag the WeaviateHybridRetriever component onto the canvas from the Component Library.
3. Set alpha to control the blend between keyword (0.0) and vector (1.0) search. The default is 0.7, which favors vector search.
4. Connect both a query string and a query_embedding (from a text embedder) to the retriever.

Connections

WeaviateHybridRetriever receives a text query string and a query_embedding (list of floats) from a text embedder. It outputs a list of Document objects you can connect to PromptBuilder or other downstream components.

Source Code

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

Usage Examples

Basic Configuration

  WeaviateHybridRetriever:
    type: haystack_integrations.components.retrievers.weaviate.hybrid_retriever.WeaviateHybridRetriever
    init_parameters:
      document_store: WeaviateDocumentStore
      top_k: 10
      alpha: 0.7

Using the Component in a Pipeline

# haystack-pipeline
components:
  text_embedder:
    type: haystack.components.embedders.sentence_transformers_text_embedder.SentenceTransformersTextEmbedder
    init_parameters:
      model: sentence-transformers/all-MiniLM-L6-v2

  document_store:
    type: haystack_integrations.document_stores.weaviate.document_store.WeaviateDocumentStore
    init_parameters:
      url:
        type: env_var
        env_vars:
        - WEAVIATE_URL
        strict: false
      auth_client_secret:
        type: env_var
        env_vars:
        - WEAVIATE_API_KEY
        strict: false

  retriever:
    type: haystack_integrations.components.retrievers.weaviate.hybrid_retriever.WeaviateHybridRetriever
    init_parameters:
      document_store: document_store
      top_k: 10
      alpha: 0.5

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

inputs:
  query:
  - text_embedder.text
  - retriever.query

outputs:
  documents: retriever.documents

Parameters

Inputs

Parameter	Type	Description
query	str	The text query to search for. Used for BM25 keyword matching.
query_embedding	List[float]	The query embedding vector. Used for vector similarity search.
filters	Optional[Dict[str, Any]]	Filters to apply when retrieving documents.
top_k	Optional[int]	The maximum number of documents to retrieve. Overrides the init-time value.
alpha	Optional[float]	The blend factor between keyword and vector search. Overrides the init-time value.
max_vector_distance	Optional[float]	The maximum vector distance threshold. Overrides the init-time value.

Outputs

Parameter	Type	Description
documents	List[Document]	A list of hybrid search results from Weaviate.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
document_store	WeaviateDocumentStore		The Weaviate document store to retrieve documents from.
filters	Optional[Dict[str, Any]]	None	Default filters to apply when retrieving documents.
top_k	int	10	The maximum number of documents to retrieve.
alpha	float	0.7	The blend factor between keyword (0.0) and vector (1.0) search. Values between 0.0 and 1.0 blend both approaches.
max_vector_distance	Optional[float]	None	The maximum allowed vector distance. Results with greater distance are excluded.
filter_policy	FilterPolicy	FilterPolicy.REPLACE	How to handle filters passed at query time. REPLACE replaces init-time filters; MERGE combines them.

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 keyword matching.
query_embedding	List[float]		The query embedding for vector search.
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.
alpha	Optional[float]	None	Blend factor override for this query.
max_vector_distance	Optional[float]	None	Maximum vector distance override for this query.

Related Information

• WeaviateBM25Retriever
• WeaviateEmbeddingRetriever
• Pipeline Components