QueryExpander

Generate multiple semantically similar queries from a single input query. It uses an LLM to create query variations, which improves retrieval recall by capturing different ways users might phrase the same question.

Key Features

• Uses an LLM to generate multiple query variations from a single query.
• Returns a JSON-structured response with the expanded queries.
• Optionally includes the original query in the output list.
• Compatible with any chat generator that returns responses in the expected JSON format.
• Supports custom prompt templates to control how the LLM generates variations.

Configuration

1. Drag the QueryExpander component onto the canvas from the Component Library.
2. Click the component to open the configuration panel.
3. Configure the parameters as needed.

Connections

QueryExpander accepts a query string and an optional n_expansions override as inputs. It outputs queries — a list of semantically similar query strings.

Typically, you connect QueryExpander between the pipeline Input component and a MultiQueryTextRetriever or MultiQueryEmbeddingRetriever. The expanded queries help find relevant documents that a single query formulation might miss.

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

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.

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.