What is range search?
Range search is the query pattern of asking for every point within a fixed distance of a query, rather than asking for a specific number of the best-ranked results. Where top-k search always returns exactly k results regardless of how good or poor they actually are in absolute terms, range search returns however many points happen to satisfy the distance threshold — that could be zero points if nothing is close enough, or it could be thousands if the query lands in an unusually dense region of the space. It’s the other major query pattern used against vector data, and the choice between range search and top-k search reflects a genuinely different question being asked of the data, not just a different way of phrasing the same request.
How exactly does a range search differ from asking for the k nearest neighbors?
A range search is defined entirely by an absolute distance threshold decided in advance: “give me every point within this exact distance of my query.” Because the threshold is fixed and absolute, the number of results a range search returns is completely determined by how the data happens to be distributed around that particular query, not by anything the query itself controls. A query landing in a dense cluster of similar points might return hundreds of results within a given threshold, while an otherwise identical threshold applied to a query landing in a sparse region might return none at all — the same numeric radius means something very different depending on how crowded the surrounding neighborhood happens to be.
Top-k search sidesteps this variability entirely by defining “how many results” as a fixed number chosen by the query itself, letting the actual distances of those k results vary depending on the data, rather than fixing the distance and letting the count vary. This is exactly why top-k search, as covered on its own glossary page, tends to be the more commonly used pattern for nearest-neighbor search over embeddings — a sensible absolute distance threshold is hard to pick in advance when the right notion of “close enough” shifts depending on how densely the surrounding region of the embedding space happens to be populated, a concern range search runs into directly and top-k search largely avoids.
Where does range search still make more sense than top-k search?
Despite this drawback, range search is the right tool whenever the actual goal of a query is genuinely about a fixed, meaningful threshold rather than about finding a specific number of best matches. A fraud detection system checking whether a new transaction‘s embedding falls suspiciously close to any known fraudulent pattern cares about a specific, meaningful notion of “close enough to be suspicious” — it wants to know whether any match exists within that threshold, and it doesn’t particularly care about being handed exactly k results if the true answer is “zero matches” or “fifty matches.” A deduplication system trying to identify near-identical records has a similar shape: the question is genuinely “does anything sufficiently similar already exist,” not “what are the k most similar things,” and forcing that question into a top-k frame by picking an arbitrary k risks either missing legitimate duplicates or forcing in false matches that don’t actually clear a meaningful similarity bar.
The common thread across these use cases is that the distance threshold itself carries real, externally defined meaning — a specific level of similarity that matters for the task, independent of how many other points happen to be nearby — rather than being an arbitrary cutoff chosen only because some fixed number of results was needed for display or downstream processing.
How does HNSW’s search algorithm actually handle a range query, given that its core design centers on top-k search?
HNSW‘s native search machinery — the dual-queue structure, the stopping criterion tied to the worst entry in a fixed-size result set — is built specifically around the top-k pattern, and adapting it to answer a range query well requires some genuine care rather than a trivial reinterpretation. One straightforward approach runs the standard greedy traversal much as it normally would, but instead of stopping once a result set of size k is filled and stable, it continues expanding and simply retains every candidate found so far that falls within the given distance threshold, discarding the notion of a fixed result-set size entirely and stopping instead once the search’s own candidate queue can no longer possibly contain anything closer than the threshold. This is generally described as range-aware termination, and it requires its own separate stopping logic distinct from the k-based criterion HNSW‘s search normally relies on, precisely because a plain top-k stopping rule has no natural way to express “stop once nothing closer than this fixed distance remains to be found.”
Because this isn’t the pattern HNSW’s construction and tuning are optimized around, range search support tends to be a secondary feature layered onto implementations built primarily for top-k queries, rather than a first-class query type with the same level of tuning attention as top-k search receives throughout the rest of this documentation.
Having drawn the contrast between range search’s fixed-threshold approach and top-k search’s fixed-count approach, the top-k search and bounded top-k heap glossary pages are worth revisiting with this comparison in mind if you haven’t already read them. From there, the ground-truth-in-a-search-benchmark glossary page is useful context for understanding how these two different query patterns each get evaluated and measured for correctness when testing an approximate search system like HNSW.