QueryExpander

Generate multiple semantically similar queries to improve retrieval recall in RAG systems. It uses an LLM to do that.

Basic Information

• Type: haystack.components.query.query_expander.QueryExpander
• Components it can connect with:
  • Input: QueryExpander receives the query to expand from the Input component.
  • MultiQueryEmbeddingRetriever or MultiQueryTextRetriever: QueryExpander sends the generated queries to one of these retrievers.

Inputs

Parameter	Type	Description
query	str	The original query to expand.
n_expansions	Optional[int]	Number of additional queries to generate.

Outputs

Parameter	Type	Description
queries	List[str]	A list of semantically similar queries generated for the original query. If include_original_query is True, it includes the original query and the expanded alternatives, otherwise only expanded queries.

Overview

QueryExpander uses an LLM to create multiple semantically similar versions of a query. This technique improves retrieval recall by capturing different ways users might phrase the same question. The component uses a default prompt that instructs the LLM to generate variations using different words and phrasings while maintaining the core meaning and intent. The generated queries are designed to work well with both keyword and semantic search retrievers.

The component returns a JSON-structured response containing the expanded queries. By default, it uses OpenAI's gpt-4.1-mini model, but you can provide any chat generator that returns responses in the expected JSON format: {"queries": ["query1", "query2", "query3"]}. You can also provide a custom prompt template to instruct the LLM how to generate the expanded queries.

Use this component in combination with MultiQueryTextRetriever or MultiQueryEmbeddingRetriever to enhance the retrieval process. The expanded queries help find relevant documents that might be missed with a single query formulation.

Usage example

This example shows how to perform retrieval with QueryExpander and MultiQueryTextRetriever. You can then send the retrieved documents to a Ranker or DocumentJoiner component to combine the results:

components:
  query_expander:
    type: haystack.components.query.query_expander.QueryExpander
    init_parameters:
      n_expansions: 3
      include_original_query: true

      chat_generator:
        type: haystack_integrations.components.generators.anthropic.chat.chat_generator.AnthropicChatGenerator
        init_parameters: {}
  multi_query_retriever:
    type: haystack.components.retrievers.multi_query_text_retriever.MultiQueryTextRetriever
    init_parameters:
      retriever:
        type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
        init_parameters:
          document_store:
            type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
          top_k: 5

connections:
- sender: query_expander.queries
  receiver: multi_query_retriever.queries

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - query_expander.query

Parameters

Init parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
chat_generator	Optional[ChatGenerator]	None	The chat generator component to use for query expansion. If None, a default OpenAIChatGenerator with gpt-4.1-mini model is used.
prompt_template	Optional[str]	None	Custom PromptBuilder template for query expansion. The template should instruct the LLM to return a JSON response with the structure: {"queries": ["query1", "query2", "query3"]}. The template should include query and n_expansions variables.
n_expansions	int	four	Number of alternative queries to generate (default: four).
include_original_query	boolean	True	Whether to include the original query in the output.

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.

Run() method parameters take precedence over initialization parameters.

Parameter	Type	Default	Description
query	str		The original query to expand.
n_expansions	Optional[int]	None	Number of additional queries to generate (not including the original). If None, uses the value from initialization. Can be zero to generate no additional queries. Must be positive.