Agentic AI Notebook
0Document Loaders1Chunking2Embedding Models3Vector Databases4Metadata5Retrievers6Hybrid Search7BM258Cross Encoder9Re-ranking10Query Expansion11Compression12Caching13RAG14LangChain Basics15ChromaDB16Streamlit17RAG Evaluation18Knowledge Graphs19Graph RAG20Entity Resolution21Graph Retrieval
RAG Engineering
Phase 3Module 11 of 22

Query Expansion

Users ask vague, abbreviated, or differently-phrased questions than documents use. 'PTO' vs 'paid time off', 'k8s' vs 'Kubernetes'. Query expansion bridges the vocabulary gap between user language and document language, reducing missed retrievals.

Query expansion is like a librarian who hears 'books about the war' and also searches for 'WWII', 'World War 2', '1940s conflict', and 'European theatre' — covering all ways the topic might be cataloged.

Visual Workflows

Start here — scroll inside each diagram frame to explore, then use + / − to zoom up to 200% if needed.

Overview

100%
Loading diagram...

Scroll inside the frame to explore · use + / − to zoom up to 200%

100%
Loading diagram...

Scroll inside the frame to explore · use + / − to zoom up to 200%

Multi-query

100%
Loading diagram...

Scroll inside the frame to explore · use + / − to zoom up to 200%

One user sentence becomes several searches.

HyDE

100%
Loading diagram...

Scroll inside the frame to explore · use + / − to zoom up to 200%

Embed a hypothetical answer when the query is too short to match docs.

Key Takeaways

  • 1.Query expansion rewrites, enriches, or decomposes user queries before retrieval — generating multiple search queries from one user question to improve recall across varied document phrasings. Techniques: (1) LLM query rewriting — GPT generates 3-5 alternative phrasings.
  • 2.(2) HyDE (Hypothetical Document Embeddings) — LLM generates a hypothetical answer, embed that instead of the query. (3) Multi-query — decompose complex questions into sub-queries.
  • 3.(4) Synonym expansion — domain thesaurus. (5) Step-back prompting — generate a broader question first.
  • 4.Production: run expanded queries in parallel, fuse results with RRF, cap total latency. Cache expanded queries for common patterns.

Real Example

Scenario

User asks 'k8s pod crash'. Expander generates: 'Kubernetes pod crash troubleshooting', 'container restart loop debugging', 'pod OOMKilled resolution'. Three parallel retrievals fuse to surface docs using any of these phrasings.

What you would do

In RAG Engineering, apply Query Expansion to this scenario: User asks 'k8s pod crash'. Identify the inputs, run the technique, validate the output, and note one thing you would monitor in production.

Practice Task

Open the Code Walkthrough below and run it locally. Change one parameter related to Query Expansion (e.g. model, temperature, top_k, or tool name), observe the difference in output, and write 2–3 sentences explaining what changed.

Code Walkthrough

Highlighted lines show where Query Expansion happens in the code.

Query Expansion
1from openai import OpenAI  # import dependencies2
3client = OpenAI()  # create API client4
5def expand_query(query: str) -> list[str]:  # define a reusable function6    response = client.chat.completions.create(  # call the API7        model="gpt-4o-mini",8        messages=[{9            "role": "user",10            "content": f"""Generate 3 alternative search queries for: "{query}"  # key line for Query Expansion11            Return as JSON list of strings."""12        }],13        response_format={"type": "json_object"},14        temperature=0.3,15    )16    import json  # import dependencies17    return json.loads(response.choices[0].message.content)["queries"]  # return the result18
19def hyde_query(query: str) -> str:  # define a reusable function20    response = client.chat.completions.create(  # call the API21        model="gpt-4o-mini",22        messages=[{23            "role": "user",24            "content": f"Write a short paragraph that would answer: {query}"  # key line for Query Expansion25        }],26        temperature=0,27    )28    return response.choices[0].message.content  # return the result

Commands

Commands to Remember

  • Multi-query: LLM generates 3 search strings from one question
  • HyDE: embed a hypothetical answer, not the raw query
  • Always also search the original query to limit drift
  • Measure recall@k — expansion can add noise

Cheat Sheet

Quick recap

quick ref
  • •Expand before retrieve
  • •HyDE = embed fake answer
  • •3 variants max
  • •Parallel search + RRF
  • •Cache expansions
  • •Skip for exact IDs/codes

Common Mistakes

  • ✕Generating too many variants — latency and cost explosion
  • ✕Sequential instead of parallel expanded retrieval
  • ✕HyDE hallucinating off-topic hypothetical documents
  • ✕Expanding queries that are already precise (SKUs, IDs)
  • ✕Not measuring whether expansion actually improves recall