What does the query-time parameter ef (search breadth) control, and how would you use it to trade off recall against latency?

ef is the size of the dynamic candidate list maintained during the layer-0 best-first search. It is the single most important query-time knob in HNSW because it lets you trade recall for latency per request without touching the index. During search, the algorithm maintains two structures: a frontier of unexplored candidates ordered by distance, and a result set of the best nodes found so far, both bounded by ef. Larger ef means the search explores more of the graph before it terminates, which reduces the probability of missing a true nearest neighbor, at the cost of more distance computations. The result set is what gets returned as top-k, so ef must be at least as large as limit; Qdrant silently raises it to max(ef, limit) if you set it lower.

The reason this is the right knob to reach for is that it decouples recall from index structure. m and ef_construct are baked into the graph and changing them requires rebuilding; ef is evaluated fresh on every query and has essentially linear cost in distance computations and roughly linear cost in latency at a fixed vector size. That means you can have different ef for different endpoints: a search-as-you-type endpoint uses ef=32 for 3ms responses, while a nightly bulk scoring job uses ef=512 for maximum recall. The same collection serves both. The shape of the recall vs ef curve is concave and dataset-dependent: on most real datasets recall rises steeply between ef=16 and ef=128, then flattens. The knee of that curve is where you want your default; past it you are paying latency for fractions of a point of recall. You should measure this curve on your own data against exact ground truth, not assume the knee is at the same place as a blog post.

The main alternative to raising ef is to improve the graph itself (higher m or ef_construct) at the cost of memory and a rebuild. If you have already rebuilt recently and memory is not the constraint, raising ef is almost always the cheaper move because it is reversible and per-request. The common mistake is setting ef very high to fix a recall problem that is actually caused by the embedding model or by aggressive payload filtering, not by HNSW. Another common mistake is assuming a higher ef always means higher latency - it does in aggregate, but for very small collections that fit in cache the difference can be in the microseconds, so it is worth measuring rather than assuming. A subtler one: on a multi-tenant collection, a single global ef can be wrong for both small and large tenants; if you cannot tune per tenant, a moderate ef with post-filtering on top can be better than a very high ef with heavy pre-filtering. Version note: the exact default of hnsw_ef has changed across releases and is not the same as limit - always set it explicitly in performance-critical paths.

Version-dependent note: query_points with SearchParams(hnsw_ef=...) is the qdrant-client 1.10+ API. On older clients the same parameter was passed to search() as search_params=SearchParams(hnsw_ef=...). The semantics are identical, but the call site differs, so pin your client version in your lockfile and do not copy snippets across major versions without checking.