Atlas: diagnose slow or bad $vectorSearch results

Slow or bad vector search

Symptom: $vectorSearch is slow, returns irrelevant results, or errors.

Diagnose, in order

1. getSearchIndexes(): is the index READY? BUILDING explains errors and empty results.
2. numDimensions in the index vs your embedding length. A mismatch breaks relevance silently or errors loudly; count the vector you send.
3. numCandidates vs limit. Too low and recall collapses (good docs never surface); way too high and latency balloons.
4. filter fields: are they declared type: "filter" in the index? Undeclared filters either error or get ignored.

Confirm

Run the same query with numCandidates raised 10x. If relevance jumps, candidates were the bottleneck. If nothing changes, the problem is dimensions or the index itself.

Fix

Correct the index definition (recreate if dimensions or fields are wrong), tune numCandidates to the recall/latency tradeoff you measured, and declare every filter field.

Verify

A known-similar document ranks first, p95 query latency is within budget, and the index stays READY (not rebuilding).

Vector search index options (numDimensions, similarity, filter fields) and query options (numCandidates, limit) per the MongoDB Atlas Search docs at https://www.mongodb.com/docs/search/indexes/manage-indexes/, verified 2026-09-26.