> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Expand

> Generate query variations using LLMs and fuse results for improved recall

![Query Expand stage showing LLM-powered query variations and result fusion](https://mintcdn.com/mixpeek/TwtTrae3Fi3EFJ72/assets/retrievers/query-expand.svg?fit=max\&auto=format\&n=TwtTrae3Fi3EFJ72\&q=85\&s=6c5d62605e1456dee20bb14c69a306ce)

The Query Expand stage uses language models to generate multiple query variations from the original query, executes searches for each variation, and fuses the results. This improves recall by capturing different phrasings and aspects of the user's intent.

![Query expansion explained: an ambiguous two-word query (jaguar speed) is expanded by an LLM into multiple reformulations covering each interpretation, each searches independently, and results fuse via Reciprocal Rank Fusion into one broader ranked list; HyDE instead generates a hypothetical answer document and embeds that paragraph for more signal. Multi-query improves recall for ambiguous queries, HyDE improves precision for short single-intent queries, and both can be combined.](https://mintcdn.com/mixpeek/7Pcnzu2AXsKNt5KO/assets/query-expansion.png?fit=max\&auto=format\&n=7Pcnzu2AXsKNt5KO\&q=85\&s=2562fa1e32816cb4898f15ee8a9a5448)

Why expansion works: a short, ambiguous query becomes several reformulations that each search independently and fuse via Reciprocal Rank Fusion; HyDE takes the opposite path and embeds a hypothetical answer instead of the question.

> [!NOTE]
>
> **Stage Category**: FILTER (Generates and fuses search results)
>
> **Transformation**: 1 query → N query variations → fused results

## When to Use

| Use Case | Description |
| - | - |
| **Improved recall** | Capture documents that match alternative phrasings |
| **Ambiguous queries** | Handle queries with multiple interpretations |
| **Synonym expansion** | Find documents using different terminology |
| **Multi-aspect search** | Break complex queries into sub-queries |

## When NOT to Use

| Scenario | Recommended Alternative |
| - | - |
| Simple keyword search | `feature_search` directly |
| Low latency requirements | Pre-compute expansions |
| Precise single-intent queries | Standard search |
| Cost-sensitive applications | Use simpler search |

## Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `feature_search_config` | object | *Required* | Full [`feature_search`](https://docs.mixpeek.com/docs/retrieval/stages/feature-search) stage parameters. The query text in its first search is the original query, and each variation replaces the query text in every search |
| `num_expansions` | integer | `3` | Number of query variations to generate (1 to 10) |
| `expansion_model` | string | `gpt-4o-mini` | LLM model for query generation |
| `expansion_prompt` | string | *auto* | Custom prompt for query generation. Use `{{QUERY}}` for the original query and `{{NUM_EXPANSIONS}}` for the count |
| `include_original` | boolean | `true` | Also run the original query alongside the variations |
| `fusion_strategy` | string | `rrf` | Result fusion: `rrf` or `linear` |
| `rrf_k` | integer | `60` | RRF constant k (1 to 1000). Lower values (20 to 40) favor precision, higher values (80 to 100) favor recall |
| `deduplicate` | boolean | `true` | Deduplicate the fused results by `document_id` |
| `expansion_timeout_ms` | integer | server default | Time budget in milliseconds for the expansion LLM call, up to 5000. On timeout the search runs on the original query only and the response carries a warning |

## Fusion Methods

| Method | Description | Best For |
| - | - | - |
| `rrf` | Reciprocal Rank Fusion | General purpose, balanced |
| `linear` | Average of a document's scores across the queries it appears in | When scores are comparable |

## Configuration Examples

```json Basic Query Expansion theme={null}
{
  "stage_name": "query_expand",
  "stage_type": "filter",
  "config": {
    "stage_id": "query_expand",
    "parameters": {
      "num_expansions": 3,
      "feature_search_config": {
        "searches": [
          {"feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "query": {"input_mode": "text", "value": "{{INPUT.query}}"}, "top_k": 30}
        ],
        "final_top_k": 30
      }
    }
  }
}
```

```json Custom Expansion Prompt theme={null}
{
  "stage_name": "query_expand",
  "stage_type": "filter",
  "config": {
    "stage_id": "query_expand",
    "parameters": {
      "num_expansions": 5,
      "expansion_prompt": "Generate {{NUM_EXPANSIONS}} alternative phrasings of this query, focusing on different synonyms and related concepts: {{QUERY}}",
      "feature_search_config": {
        "searches": [
          {"feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "query": {"input_mode": "text", "value": "{{INPUT.query}}"}, "top_k": 20}
        ],
        "final_top_k": 20
      }
    }
  }
}
```

```json High-Recall Configuration theme={null}
{
  "stage_name": "query_expand",
  "stage_type": "filter",
  "config": {
    "stage_id": "query_expand",
    "parameters": {
      "expansion_model": "gpt-4o",
      "num_expansions": 5,
      "fusion_strategy": "rrf",
      "feature_search_config": {
        "searches": [
          {"feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "query": {"input_mode": "text", "value": "{{INPUT.query}}"}, "top_k": 50}
        ],
        "final_top_k": 50
      }
    }
  }
}
```

```json Domain-Specific Expansion theme={null}
{
  "stage_name": "query_expand",
  "stage_type": "filter",
  "config": {
    "stage_id": "query_expand",
    "parameters": {
      "num_expansions": 4,
      "expansion_prompt": "Generate {{NUM_EXPANSIONS}} medical search queries that capture different aspects of: {{QUERY}}. Include medical terminology and layman's terms.",
      "feature_search_config": {
        "searches": [
          {"feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "query": {"input_mode": "text", "value": "{{INPUT.query}}"}, "top_k": 25}
        ],
        "final_top_k": 25
      }
    }
  }
}
```

## How Query Expansion Works

1. **Original Query**: "how to fix memory leaks"
2. **LLM Generates Variations**:
   * "memory leak detection and resolution"
   * "debugging memory issues in applications"
   * "preventing memory leaks in code"
3. **Execute Searches**: Run the `feature_search_config` for the original query (unless `include_original` is `false`) and for each variation, concurrently
4. **Fuse Results**: Combine using RRF or linear fusion
5. **Return**: Deduplicated, ranked result set

## Reciprocal Rank Fusion (RRF)

RRF combines results from multiple queries using the formula:

```
score(doc) = Σ 1 / (k + rank_i)
```

Where `k` is `rrf_k` (60 by default), and `rank_i` is the document's rank in query i's results.

| Advantage | Description |
| - | - |
| Score-agnostic | Works with different scoring scales |
| Rank-based | Focuses on relative ordering |
| Self-balancing | No manual weight tuning |

## Output Schema

Each returned document carries the fused result in its `score`. With `rrf`, a document ranked first by all four queries scores 4 / (60 + 1), about 0.066.

The stage metadata reports how the run went:

```json theme={null}
{
  "original_query": "how to fix memory leaks",
  "expansions": [
    "memory leak detection and resolution",
    "debugging memory issues in applications",
    "preventing memory leaks in code"
  ],
  "queries_executed": 4,
  "llm_calls": 1,
  "expansion_timed_out": false,
  "fusion_strategy": "rrf",
  "rrf_k": 60,
  "total_results_before_fusion": 120,
  "final_result_count": 74
}
```

## Performance

| Metric | Value |
| - | - |
| **Latency** | 300-800ms (LLM + searches) |
| **LLM calls** | 1 per execution |
| **Search calls** | `num_expansions` + 1, run concurrently (`num_expansions` when `include_original` is `false`) |
| **Token usage** | \~50-100 tokens |

> [!WARNING]
>
> Query expansion adds latency due to LLM generation and multiple searches. Use judiciously for queries where recall improvement justifies the cost.

## Common Pipeline Patterns

### Expanded Search + Rerank

```json theme={null}
[
  {
    "stage_name": "query_expand",
    "stage_type": "filter",
    "config": {
      "stage_id": "query_expand",
      "parameters": {
        "num_expansions": 3,
        "feature_search_config": {
          "searches": [
            {"feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "query": {"input_mode": "text", "value": "{{INPUT.query}}"}, "top_k": 50}
          ],
          "final_top_k": 50
        }
      }
    }
  },
  {
    "stage_name": "rerank",
    "stage_type": "sort",
    "config": {
      "stage_id": "rerank",
      "parameters": {
        "inference_name": "BAAI__bge_reranker_v2_m3",
        "top_k": 10
      }
    }
  }
]
```

### Expansion + Filter + Summarize

```json theme={null}
[
  {
    "stage_name": "query_expand",
    "stage_type": "filter",
    "config": {
      "stage_id": "query_expand",
      "parameters": {
        "num_expansions": 4,
        "feature_search_config": {
          "searches": [
            {"feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "query": {"input_mode": "text", "value": "{{INPUT.query}}"}, "top_k": 30}
          ],
          "final_top_k": 30
        }
      }
    }
  },
  {
    "stage_name": "structured_filter",
    "stage_type": "filter",
    "config": {
      "stage_id": "attribute_filter",
      "parameters": {
        "field": "metadata.verified",
        "operator": "eq",
        "value": true
      }
    }
  },
  {
    "stage_name": "summarize",
    "stage_type": "reduce",
    "config": {
      "stage_id": "summarize",
      "parameters": {
        "provider": "google",
        "model_name": "gemini-2.5-flash-lite",
        "prompt": "Answer this question: {{INPUT.query}}\n\nBased on these documents:\n{{DOCUMENTS}}"
      }
    }
  }
]
```

## Cost Optimization

| Strategy | Impact |
| - | - |
| Reduce `num_expansions` | Fewer searches |
| Use cheaper LLM | `expansion_model` of `gpt-4o-mini` vs `gpt-4o` |
| Lower `top_k` in `feature_search_config` | Less fusion overhead |
| Cache common expansions | Reduce LLM calls |

## Error Handling

| Error | Behavior |
| - | - |
| LLM failure | Fall back to original query, with a warning in the response |
| Empty expansions | Use original query only |
| Expansion timeout | Search runs on the original query only, with a warning that names `expansion_timeout_ms` |

## Related

* [Feature Search](https://docs.mixpeek.com/docs/retrieval/stages/feature-search.md) - Single query search
* [Feature Search](https://docs.mixpeek.com/docs/retrieval/stages/feature-search.md) - Vector + text search
* [Rerank](https://docs.mixpeek.com/docs/retrieval/stages/rerank.md) - Re-score fused results


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.