Query Expand

Query Expand stage showing LLM-powered query variations and result fusion

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. — 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.

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` 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

{
  "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
      }
    }
  }
}

{
  "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
      }
    }
  }
}

{
  "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
      }
    }
  }
}

{
  "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

Original Query: “how to fix memory leaks”
LLM Generates Variations:
- “memory leak detection and resolution”
- “debugging memory issues in applications”
- “preventing memory leaks in code”
Execute Searches: Run the feature_search_config for the original query (unless include_original is false) and for each variation, concurrently
Fuse Results: Combine using RRF or linear fusion
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:

{
  "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

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

[
  {
    "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

[
  {
    "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`

Feature Search - Single query search
Feature Search - Vector + text search
Rerank - Re-score fused results

Get started

Connect your data

Extract features

Build retrievers

Enrich & organize

Integrate & operate

Resources

When to Use

When NOT to Use

Parameters

Fusion Methods

Configuration Examples

How Query Expansion Works

Reciprocal Rank Fusion (RRF)

Output Schema

Performance

Common Pipeline Patterns

Expanded Search + Rerank

Expansion + Filter + Summarize

Cost Optimization

Error Handling

​When to Use

​When NOT to Use

​Parameters

​Fusion Methods

​Configuration Examples

​How Query Expansion Works

​Reciprocal Rank Fusion (RRF)

​Output Schema

​Performance

​Common Pipeline Patterns

​Expanded Search + Rerank

​Expansion + Filter + Summarize

​Cost Optimization

​Error Handling

​Related

When to Use

When NOT to Use

Parameters

Fusion Methods

Configuration Examples

How Query Expansion Works

Reciprocal Rank Fusion (RRF)

Output Schema

Performance

Common Pipeline Patterns

Expanded Search + Rerank

Expansion + Filter + Summarize

Cost Optimization

Error Handling

Related