Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorshnsw.ef_search sets how many candidates pgvector considers during an HNSW query. If that search budget is too small, approximate search can miss a chunk that exact nearest-neighbor search would return. Raising the setting can improve recall, but usually costs latency; first measure the gap against exact search, then tune the budget and investigate the rest of the retrieval pipeline if the gap persists.
Why an HNSW query can miss the nearest chunk
HNSW is an approximate nearest-neighbor method. It organizes vectors into layered proximity graphs: a search starts in an upper layer and descends toward likely neighbors instead of scoring every stored vector. That makes search efficient, but the returned top results can differ from exact k-nearest-neighbor results. A mismatch alone does not prove that the data or embeddings are defective. The original HNSW paper describes the graph structure; Elasticsearch’s kNN API documentation likewise explains that HNSW is approximate.
As an Amazon Associate I earn from qualifying purchases.
In pgvector, hnsw.ef_search is the query-time candidate-list setting. A larger value makes the search consider more candidates and generally improves recall at the cost of speed. It does not change what “nearest” means: the distance metric and operator still determine how vectors are ranked. pgvector’s documentation lists a default of 40, a range of 1–1000, and advises setting the value at least as high as the query’s LIMIT, since an index scan returns at most about ef_search rows. These are pgvector-specific documented settings, not universal HNSW defaults.
How to tell whether ef_search is the problem
Verify the query and index
Confirm that the query uses the intended HNSW index, distance operator, and matching operator class. Check the result LIMIT, filters, and deployed database version as well. A metric or operator-class mismatch can make a query rank vectors differently from the comparison you intended; filtering and result limits also affect which chunks can appear. Consult pgvector’s documentation for its index and query behavior.
#1 Best Overall
Compare approximate results with exact results
Use a representative set of production-like queries and compare the approximate top-k IDs with an exact nearest-neighbor result for each query. In pgvector, exact search scans every row, so keep the evaluation workload appropriately sized. Calculate recall@k: the number of exact top-k results also found in the approximate top-k, divided by k. This isolates neighbor-retrieval fidelity; it does not establish whether the chunks are useful to a reader or whether a RAG answer is correct. Qdrant’s recall tutorial explains the distinction between ANN recall and broader retrieval quality.
Raise the query-time budget in controlled steps
In pgvector, test higher hnsw.ef_search values while holding the query set and other settings constant. Keep the value at least as high as the result LIMIT, and record recall@k and query latency together. If you want the change to apply only to one transaction, pgvector supports SET LOCAL:
BEGIN;
SET LOCAL hnsw.ef_search = 100;
SELECT id
FROM chunks
ORDER BY embedding <=> '[query vector]'
LIMIT 10;
COMMIT;Replace the example table, column, operator, and vector with those used by your schema and distance metric. The value 100 is an example to test, not a recommended setting for every workload. SET LOCAL is scoped to the current transaction, so run the measured query inside that transaction.
Free tools Windows power users keep installed
One-click scans. No signup required.
Use the matching setting in your vector engine
The same search-budget idea appears under different names, with implementation-specific semantics and defaults. Do not copy a numeric value from one engine into another and assume it will behave the same way.
Rank #3
| Engine | Query-time search setting | What to verify |
|---|---|---|
| pgvector | hnsw.ef_search |
Current default, allowed range, query LIMIT, and transaction scope in the pgvector documentation. |
| Qdrant | hnsw_ef |
How the deployed configuration controls search recall and how it interacts with graph construction, in Qdrant’s ANN recall tutorial. |
| Weaviate | ef |
Whether dynamic ef is in use and the release-specific behavior in Weaviate’s vector-index documentation. |
| Elasticsearch | num_candidates |
Candidate handling, including per-segment search and the relevant tuning options in Elastic’s vector kNN tuning documentation. |
These labels are related controls, not interchangeable knobs. Follow documentation for the exact engine and release you run.
If higher ef_search does not fix recall
Inspect graph construction
Search-time tuning has limits. In pgvector, m and ef_construction affect HNSW index construction. The current documentation lists defaults of 16 and 64, respectively; higher ef_construction may improve recall but slows index building and inserts. In Qdrant, m and ef_construct can also limit search recall, and changing graph construction settings may require rebuilding the index. Check the documentation for the release you have deployed because defaults and behavior may change. pgvector documentation and Qdrant’s tutorial describe these trade-offs.
Distinguish low ANN recall from poor relevance
If approximate search returns the same top results as exact search but those chunks are still unhelpful, increasing the HNSW search budget will not solve the underlying relevance problem. Examine the query, embedding model, chunking strategy, distance metric, filters, or retrieval design. ANN recall measures agreement with exact vector neighbors; it is only one layer of end-to-end retrieval quality, as Qdrant’s recall guidance emphasizes.
Choose a setting using quality and cost
Evaluate candidate settings on the same representative query sample and compare the outcomes that matter to your application:
Best Value
- Recall@k: how many exact neighbors the approximate search recovers.
- Latency: the query-time cost of searching more candidates.
- Result count: whether the search budget is large enough for the requested
LIMIT. - Index costs: build time, insertion overhead, and whether a construction-setting change calls for an index rebuild.
- Quality beyond ANN: whether retrieved chunks are relevant and improve the final application output.
Implementation-specific advice should stay in context: Weaviate’s documentation notes diminishing recall gains above ef 512 for its implementation. That is not a general threshold for pgvector or other HNSW engines. For quantized Elasticsearch vectors, rescoring can recover some recall, but it is a separate mechanism from increasing HNSW num_candidates; see Elastic’s tuning guidance.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
