Query Understanding
Raw search boxes get typos, vague words, and buried details like size 10. Query understanding cleans the spelling, labels the intent, and splits filters from search text before retrieval runs.
Why Does This Exist?
Your retriever is literal and your users are not. You tuned the index, picked embeddings, added a reranker, and then a real person types cheap runing shoes size 10 and gets hiking boots in size 9. You will see this daily once strangers touch your box.
Two things broke at once. A keyword index has no entry for runing, so it misses every running page. A vector index fails quieter: it folds size 10 into the same embedding as the style words, so closeness in vector space stops meaning the right size. Raw string in, confident wrong answers out.
Query understanding is the cleanup pass before retrieval. It fixes the spelling, labels what the shopper wants, and pulls exact details out of the prose so they can run as hard filters instead of vibes.
That scope is narrow on purpose. Rephrasing a vague ask into a better sentence is query rewriting. Splitting one hard question into subquestions is query decomposition. Sending the cleaned pieces to keyword and vector indexes together is hybrid search. This page is the step before all of that: raw string in, three clean outputs out.
The one idea you need first: keyword search matches exact terms, which is why BM25 lives or dies on spelling, while vector search matches meaning by position. Query understanding decides which words deserve which treatment, then routes them accordingly.
Skip the whole pass when queries arrive clean already. Exact SKU lookups, pasted error codes, or a picker where users choose from a list do not need it. There the extra step buys nothing, and each rewrite is a fresh chance to corrupt a good query.
Think of It Like This
A takeout counter and its ticket rail
You mumble at a busy takeout counter: uh, chicken, extra spicy, no peanuts, fast. The cashier does not shout your mumble at the cooks. They hang a ticket: dish chicken curry, heat extra, allergy no peanuts, rush yes. Four jobs happened. They heard through the noise, named the dish, pulled hard constraints off to the side, and flagged urgency.
That maps part for part. Your mumble is the raw query. The dish line is the cleaned search text. Allergy and rush are the filter and the intent. The cooks never have to guess what no peanuts means from context.
Where it stops: the ticket cannot fix a vague order. Extra tasty stays vague, and a good cashier asks back instead of guessing. Your pipeline should do the same. Keep the raw string around, and clarify or fall back when confidence is low.
How It Actually Works
One messy string enters. Three clean outputs leave, plus a routing tag. Nothing here ranks documents. It only decides what each word is for.
From one string to three outputs
Name the pieces once, because every stage touches them:
- is the raw string the user typed, exactly as received, typos included.
- is the cleaned search text: lowercased, spell fixed, with filter words removed.
- is the intent label: one short tag such as buy, support, or learn, used to route the request.
- is the filter set: exact constraints such as size equals 10, applied before ranking.
- is the expansion set: added synonyms such as sneakers for shoes, used to catch wording variants.
- is edit distance: the smallest count of insertions, deletions, or substitutions turning string into string .
The pass runs in four small moves. First, normalize: lowercase, strip punctuation, and fix tokens whose edit distance to a known word is tiny. Second, classify from the whole string, because cancel my subscription should route to support, not to search. Third, extract entities into and delete them from the search text, so size 10 never gets averaged into an embedding. Fourth, expand with for recall, so docs that say sneakers still match a shoes query. Retrieval then scores only rows passing , using plus .
The trade you are making: each stage costs latency and adds a fresh error source. You pay it when queries are messy, short, and full of filters. You do not pay it for exact lookups.
Worked example with small numbers
Take as cheap runing shoes size 10. Five whitespace tokens. The suspicious one is runing.
Compare it against running. Align them: r u n i n g against r u n n i n g. The second string has one extra n after the third letter, and everything else matches. So equals 1, a single insertion. That is below any sane fix threshold, so it becomes running. Cleaned text is cheap running shoes. Filters hold size equals 10. Intent is buy. Expansions add sneakers alongside shoes.
Now the payoff on a toy catalog, stated so you can check the arithmetic. Say equals 200 listings before filtering, where is the catalog size. Suppose 46 of them carry size 10. The filter keeps 46 of 200, which is , or 23 percent. It prunes listings before any vector math runs. Your embedder now ranks 46 candidates instead of 200, and none of them is the wrong size. The same numbers sit in the diagram above. Expansion does the other half: a doc that says lightweight sneakers for daily running shares no exact term with shoes, so the raw query misses it and the expanded query catches it.
What each step assumes, and how it breaks
Normalization assumes a near miss is an accident. True for runing, false for a product code like RUNING-1, which a fixer will mangle into running. Extraction assumes a nearby word names the number, so 10 next to size means size. False for iphone 10, where 10 is the model. Expansion assumes the synonym fits this store. Sneakers helps a shoe shop and pollutes a dress shoe boutique. Metadata filtering is where the extracted constraints go, so read that page for how hard filters apply. When queries are already precise, turn this pass off or run it in shadow mode and log what it would have changed.
Code
The point is the split, not the spelling fix. This toy parser cleans one typo, pulls the size number into a filter dict, and leaves real search text behind. No network calls, no keys.
import re
def clean(text: str) -> str: fixes: dict[str, str] = {"runing": "running"} return " ".join(fixes.get(tok, tok) for tok in text.lower().split())
def split_filters(cleaned: str) -> tuple[str, dict[str, int]]: m: re.Match[str] | None = re.search(r"size\s+(\d+)", cleaned) filters: dict[str, int] = {} text: str = cleaned if m: filters["size"] = int(m.group(1)) text = re.sub(r"\s*size\s+\d+", "", cleaned).strip() return text, filters
q: str = "cheap runing shoes size 10"c: str = clean(q)t: strf: dict[str, int]t, f = split_filters(c)print(c) # -> cheap running shoes size 10print(t) # -> cheap running shoesprint(f) # -> {'size': 10}The three prints agree with the worked example: full cleaned string, search text with the filter removed, and the filter dict that runs before ranking.
Watch Out For
Fixing a name into the wrong word
The symptom: an exact product, code, or surname vanishes from results, and the page cheerfully reports showing results for something else. Someone searches for the trail shoe Runin Flow and gets running flow instead. Or a new brand name gets corrected into a common word within weeks of launch.
The cause is a fixer with no allowlist. Cap the damage: only auto fix when is 1 for short tokens, keep a per store allowlist of names and codes the fixer may never touch, and always keep the raw around. Show the escape hatch on screen: results for running, with a search instead for runin link. Log every rewrite so you can see which fix hurts.
A confident filter that returns nothing
The symptom: zero results on a query that plainly should match. Iphone 10 becomes size equals 10. Under 800 without a currency word becomes size 800. One bad extract wipes out the whole catalog, and the empty page looks like you carry nothing.
The cause is treating a guess as a fact. Never apply a low confidence extract as a hard filter without a fallback. Check the filter against the catalog first. If it would empty the results, drop the weakest extract and retry, softening it into a ranking boost instead of a gate. Record which extract you dropped so the next debug session starts from evidence.
The Quick Version
- Query understanding turns one raw string into cleaned search text, a filter set, and expansions before any index runs.
- Spelling belongs to keyword search and meaning belongs to vectors, so the pass routes each word to the right side.
- Pull exact details like size 10 out of the prose into a metadata filter instead of embedding them.
- Every stage adds latency and a new way to be wrong, so skip the pass for exact SKUs and clean picker input.
- Keep the raw query, cap fixes at tiny edit distances, and fall back rather than serve zero results.