Rewrite queries

The gap between what people type and what they mean

A visitor types 'why is it slow' into a search box, meaning something much more specific — page load time, database latency, a particular feature lagging — but the search index has no way to guess which. rag.query_rewrite sits in front of that gap: it takes the underspecified question and produces a version with the missing context filled in or the ambiguity narrowed, so whatever searches or retrieves against it afterward has something worth matching.

What the request looks like

POST /rag/query-rewrite with the original question, and the task runs asynchronously — you get a task_id right away, and the rewritten query arrives afterward through a signed webhook call or a signed link valid for 24 hours. The output is a clearer, more searchable version of the same question, built to feed directly into a search index or a retrieval step rather than to be read by a person.

Query expansion isn't a new idea, but it's still an unsolved default

Information retrieval researchers have worked on the vocabulary mismatch problem for decades — the fact that a searcher's words and a document's words rarely line up exactly even when they mean the same thing — through techniques like adding synonyms or related terms to a query before running it. Most search boxes still ship with none of that: they run the raw string the user typed and call it done, which is why so many searches return nothing useful on the first try. Rewriting the query before searching addresses the mismatch at its source instead of hoping the underlying index will compensate.

Where it sits in a retrieval pipeline

This endpoint is a pre-processing step, not a final answer — it's meant to run before a search call, a retrieval-augmented answer, or any system that needs a well-formed query to work well. Because it's billed per request plus per query and runs async, it drops cleanly in front of a larger pipeline: a search box rewrites the query first, then passes the rewritten version to whatever retrieval or search system does the actual matching, all without a person in the loop.

What actually improves once queries are cleaned up

A downstream retrieval system built well can still return weak results if what it's given to search against is a vague three-word fragment; feed it a clearer, disambiguated query and the same retrieval logic returns noticeably more relevant matches. Teams that add this step in front of an existing search or RAG pipeline are typically fixing search quality without touching the retrieval system itself, since the fix happens one step earlier, at the question, not at the index.