1  ---
  2  title: "Query"
  3  id: query-api
  4  description: "Components for query processing and expansion."
  5  slug: "/query-api"
  6  ---
  7  
  8  
  9  ## query_expander
 10  
 11  ### QueryExpander
 12  
 13  A component that returns a list of semantically similar queries to improve retrieval recall in RAG systems.
 14  
 15  The component uses a chat generator to expand queries. The chat generator is expected to return a JSON response
 16  with the following structure:
 17  
 18  ```json
 19  {"queries": ["expanded query 1", "expanded query 2", "expanded query 3"]}
 20  ```
 21  
 22  ### Usage example
 23  
 24  ```python
 25  from haystack.components.generators.chat.openai import OpenAIChatGenerator
 26  from haystack.components.query import QueryExpander
 27  
 28  expander = QueryExpander(
 29      chat_generator=OpenAIChatGenerator(model="gpt-4.1-mini"),
 30      n_expansions=3
 31  )
 32  
 33  result = expander.run(query="green energy sources")
 34  print(result["queries"])
 35  # Output: ['alternative query 1', 'alternative query 2', 'alternative query 3', 'green energy sources']
 36  # Note: Up to 3 additional queries + 1 original query (if include_original_query=True)
 37  
 38  # To control total number of queries:
 39  expander = QueryExpander(n_expansions=2, include_original_query=True)  # Up to 3 total
 40  # or
 41  expander = QueryExpander(n_expansions=3, include_original_query=False)  # Exactly 3 total
 42  ```
 43  
 44  #### __init__
 45  
 46  ```python
 47  __init__(
 48      *,
 49      chat_generator: ChatGenerator | None = None,
 50      prompt_template: str | None = None,
 51      n_expansions: int = 4,
 52      include_original_query: bool = True
 53  ) -> None
 54  ```
 55  
 56  Initialize the QueryExpander component.
 57  
 58  **Parameters:**
 59  
 60  - **chat_generator** (<code>ChatGenerator | None</code>) – The chat generator component to use for query expansion.
 61    If None, a default OpenAIChatGenerator with gpt-4.1-mini model is used.
 62  - **prompt_template** (<code>str | None</code>) – Custom [PromptBuilder](https://docs.haystack.deepset.ai/docs/promptbuilder)
 63    template for query expansion. The template should instruct the LLM to return a JSON response with the
 64    structure: `{"queries": ["query1", "query2", "query3"]}`. The template should include 'query' and
 65    'n_expansions' variables.
 66  - **n_expansions** (<code>int</code>) – Number of alternative queries to generate (default: 4).
 67  - **include_original_query** (<code>bool</code>) – Whether to include the original query in the output.
 68  
 69  #### to_dict
 70  
 71  ```python
 72  to_dict() -> dict[str, Any]
 73  ```
 74  
 75  Serializes the component to a dictionary.
 76  
 77  **Returns:**
 78  
 79  - <code>dict\[str, Any\]</code> – Dictionary with serialized data.
 80  
 81  #### from_dict
 82  
 83  ```python
 84  from_dict(data: dict[str, Any]) -> QueryExpander
 85  ```
 86  
 87  Deserializes the component from a dictionary.
 88  
 89  **Parameters:**
 90  
 91  - **data** (<code>dict\[str, Any\]</code>) – Dictionary with serialized data.
 92  
 93  **Returns:**
 94  
 95  - <code>QueryExpander</code> – Deserialized component.
 96  
 97  #### run
 98  
 99  ```python
100  run(query: str, n_expansions: int | None = None) -> dict[str, list[str]]
101  ```
102  
103  Expand the input query into multiple semantically similar queries.
104  
105  The language of the original query is preserved in the expanded queries.
106  
107  **Parameters:**
108  
109  - **query** (<code>str</code>) – The original query to expand.
110  - **n_expansions** (<code>int | None</code>) – Number of additional queries to generate (not including the original).
111    If None, uses the value from initialization. Can be 0 to generate no additional queries.
112  
113  **Returns:**
114  
115  - <code>dict\[str, list\[str\]\]</code> – Dictionary with "queries" key containing the list of expanded queries.
116    If include_original_query=True, the original query will be included in addition
117    to the n_expansions alternative queries.
118  
119  **Raises:**
120  
121  - <code>ValueError</code> – If n_expansions is not positive (less than or equal to 0).
122  
123  #### warm_up
124  
125  ```python
126  warm_up() -> None
127  ```
128  
129  Warm up the LLM provider component.