MongoDB Atlas: create a Vector Search index that actually works

Create the vector search index

Use mongosh, a driver, or the Atlas UI (Search tab, JSON editor). The definition shape:

db.docs.createSearchIndex("vec_idx", "vectorSearch", {
  fields: [
    { type: "vector", path: "embedding", numDimensions: 1536, similarity: "cosine" },
    { type: "filter", path: "tenantId" }
  ]
});

Rules

• The index type must be vectorSearch, not search. A full-text index will not serve $vectorSearch.
• numDimensions must exactly equal your embedding model's output size (1536 for text-embedding-ada-002, 3072 for text-embedding-3-large, etc.). A mismatch means broken results or errors; the index cannot guess.
• similarity: cosine, dotProduct, or euclidean. Match what your embedding model expects; cosine is the safe default.
• Prefilter fields must be declared as type: "filter". A plain $match after $vectorSearch filters after the top-k, silently dropping results you expected.
• Index builds are asynchronous. Poll db.docs.getSearchIndexes() until status is READY before querying. Querying early gives "index not found" errors.

Verify

getSearchIndexes() shows the index with status READY, and a trivial $vectorSearch with a real embedding returns scored results.

Vector search index definition (type vectorSearch, fields with type vector and filter, numDimensions, similarity options) and the READY status requirement verified against current MongoDB Atlas Search documentation, including https://www.mongodb.com/docs/search/indexes/manage-indexes/, on 2026-09-26.