Skip to main content
Version: 2.32-unstable

Query

query_expander​

QueryExpander​

A component that returns a list of semantically similar queries to improve retrieval recall in RAG systems.

The component uses a chat generator to expand queries. The chat generator is expected to return a JSON response with the following structure:

json
{"queries": ["expanded query 1", "expanded query 2", "expanded query 3"]}

Usage example​

python
from haystack.components.generators.chat.openai import OpenAIChatGenerator
from haystack.components.query import QueryExpander

expander = QueryExpander(
    chat_generator=OpenAIChatGenerator(model="gpt-4.1-mini"),
    n_expansions=3
)

result = expander.run(query="green energy sources")
print(result["queries"])
# Output: ['alternative query 1', 'alternative query 2', 'alternative query 3', 'green energy sources']
# Note: Up to 3 additional queries + 1 original query (if include_original_query=True)

# To control total number of queries:
expander = QueryExpander(n_expansions=2, include_original_query=True)  # Up to 3 total
# or
expander = QueryExpander(n_expansions=3, include_original_query=False)  # Exactly 3 total

init​

python
__init__(
    *,
    chat_generator: ChatGenerator | None = None,
    prompt_template: str | None = None,
    n_expansions: int = 4,
    include_original_query: bool = True
) -> None

Initialize the QueryExpander component.

Parameters:

  • chat_generator (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 (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) – Number of alternative queries to generate (default: 4).
  • include_original_query (bool) – Whether to include the original query in the output.

to_dict​

python
to_dict() -> dict[str, Any]

Serializes the component to a dictionary.

Returns:

  • dict[str, Any] – Dictionary with serialized data.

from_dict​

python
from_dict(data: dict[str, Any]) -> QueryExpander

Deserializes the component from a dictionary.

Parameters:

  • data (dict[str, Any]) – Dictionary with serialized data.

Returns:

  • QueryExpander – Deserialized component.

run​

python
run(query: str, n_expansions: int | None = None) -> dict[str, list[str]]

Expand the input query into multiple semantically similar queries.

The language of the original query is preserved in the expanded queries.

Parameters:

  • query (str) – The original query to expand.
  • n_expansions (int | None) – Number of additional queries to generate (not including the original). If None, uses the value from initialization. Must be a positive integer.

Returns:

  • dict[str, list[str]] – Dictionary with "queries" key containing the list of expanded queries. If include_original_query=True, the original query will be included in addition to the n_expansions alternative queries.

Raises:

  • ValueError – If n_expansions is not positive (less than or equal to 0).

run_async​

python
run_async(query: str, n_expansions: int | None = None) -> dict[str, list[str]]

Asynchronously expand the input query into multiple semantically similar queries.

The language of the original query is preserved in the expanded queries.

This is the asynchronous version of the run method. It has the same parameters and return values but can be used with await in an async code. If the chat generator only implements a synchronous run method, it is executed in a thread to avoid blocking the event loop.

Parameters:

  • query (str) – The original query to expand.
  • n_expansions (int | None) – Number of additional queries to generate (not including the original). If None, uses the value from initialization. Must be a positive integer.

Returns:

  • dict[str, list[str]] – Dictionary with "queries" key containing the list of expanded queries. If include_original_query=True, the original query will be included in addition to the n_expansions alternative queries.

Raises:

  • ValueError – If n_expansions is not positive (less than or equal to 0).

warm_up​

python
warm_up() -> None

Warm up the underlying chat generator.

warm_up_async​

python
warm_up_async() -> None

Warm up the underlying chat generator on the serving event loop.

close​

python
close() -> None

Release the underlying chat generator's resources.

close_async​

python
close_async() -> None

Release the underlying chat generator's async resources.