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
`model`	string	Required	LLM model for query generation
`query`	string	`{{INPUT.query}}`	Original query to expand
`num_variations`	integer	`3`	Number of query variations to generate
`vector_index`	string	Required	Vector index for searches
`top_k`	integer	`20`	Results per query variation
`fusion_strategy`	string	`rrf`	Result fusion: `rrf` or `linear`
`expansion_prompt`	string	auto	Custom prompt for query generation

Fusion Methods

Method	Description	Best For
`rrf`	Reciprocal Rank Fusion	General purpose, balanced
`linear`	Weighted score combination	When scores are comparable
`max`	Take maximum score	When any match is good

Configuration Examples

{
  "stage_name": "query_expand",
  "stage_type": "filter",
  "config": {
    "stage_id": "query_expand",
    "parameters": {
      "model": "gpt-4o-mini",
      "query": "{{INPUT.query}}",
      "vector_index": "text_extractor_v1_embedding",
      "num_variations": 3,
      "top_k": 30
    }
  }
}

{
  "stage_name": "query_expand",
  "stage_type": "filter",
  "config": {
    "stage_id": "query_expand",
    "parameters": {
      "model": "gpt-4o-mini",
      "query": "{{INPUT.query}}",
      "vector_index": "text_extractor_v1_embedding",
      "num_variations": 5,
      "top_k": 20,
      "expansion_prompt": "Generate {{num_variations}} alternative phrasings of this query, focusing on different synonyms and related concepts: {{query}}"
    }
  }
}

{
  "stage_name": "query_expand",
  "stage_type": "filter",
  "config": {
    "stage_id": "query_expand",
    "parameters": {
      "model": "gpt-4o",
      "query": "{{INPUT.query}}",
      "vector_index": "text_extractor_v1_embedding",
      "num_variations": 5,
      "top_k": 50,
      "fusion_strategy": "rrf"
    }
  }
}

{
  "stage_name": "query_expand",
  "stage_type": "filter",
  "config": {
    "stage_id": "query_expand",
    "parameters": {
      "model": "gpt-4o-mini",
      "query": "{{INPUT.query}}",
      "vector_index": "medical_embedding",
      "num_variations": 4,
      "expansion_prompt": "Generate {{num_variations}} medical search queries that capture different aspects of: {{query}}. Include medical terminology and layman's terms."
    }
  }
}

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 vector search for each variation
Fuse Results: Combine using RRF or other fusion method
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 typically 60, 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 document includes fusion metadata:

{
  "document_id": "doc_123",
  "content": "Document content...",
  "score": 0.87,
  "query_expand": {
    "matched_variations": ["memory leak detection", "debugging memory issues"],
    "fusion_score": 0.87,
    "individual_ranks": [2, 5, null]
  }
}

Performance

Metric	Value
Latency	300-800ms (LLM + searches)
LLM calls	1 per execution
Search calls	N (num_variations)
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": {
        "model": "gpt-4o-mini",
        "query": "{{INPUT.query}}",
        "vector_index": "text_extractor_v1_embedding",
        "num_variations": 3,
        "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": {
        "model": "gpt-4o-mini",
        "query": "{{INPUT.query}}",
        "vector_index": "text_extractor_v1_embedding",
        "num_variations": 4,
        "top_k": 30
      }
    }
  },
  {
    "stage_name": "structured_filter",
    "stage_type": "filter",
    "config": {
      "stage_id": "attribute_filter",
      "parameters": {
        "conditions": {
          "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 based on the documents: {{INPUT.query}}"
      }
    }
  }
]

Cost Optimization

Strategy	Impact
Reduce num_variations	Fewer searches
Use cheaper LLM	`gpt-4o-mini` vs `gpt-4o`
Lower top_k per variation	Less fusion overhead
Cache common expansions	Reduce LLM calls

Error Handling

Error	Behavior
LLM failure	Fall back to original query
Search failure	Skip that variation
Empty expansions	Use original query only
Timeout	Return partial results

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