MongoDB Atlas Vector Search Tutorial: Build Semantic Search for Free

Large language models are powerful, but they only know what they were trained on. To make them useful on your own data, such as product docs, support tickets or internal knowledge, you need a way to find the most relevant information and hand it to the model at query time. That pattern is Retrieval-Augmented Generation (RAG), and vector search is the engine behind it.

If your data already lives in MongoDB, MongoDB Atlas Vector Search lets you store embeddings next to your documents and query them with the same aggregation framework. You do not need a paid embedding API to try it. In this tutorial you will build semantic search on the Atlas free tier in two ways: with automatic embeddings (Voyage AI) where Atlas generates the vectors for you, and with open-source embeddings that you generate locally.

What Is MongoDB Atlas Vector Search?

Atlas Vector Search is a feature of MongoDB Atlas that indexes vector embeddings stored in your documents and finds the nearest neighbors to a query vector. An embedding is a list of numbers that represents the meaning of a piece of text, so texts with similar meaning end up close together in vector space.

Key points from the official documentation:

• Embeddings are stored as arrays of numbers in a regular document field, alongside your other data.
• You define a vectorSearch type index on that field, and Atlas keeps it in sync as data changes.
• You query with the $vectorSearch aggregation stage, so results can be combined with $match, $project, $lookup and other stages.
• It supports both approximate nearest neighbor (ANN) search and exact nearest neighbor (ENN) search.

Why Use Vector Search for LLM Applications?

LLMs have context limits and can hallucinate when they lack facts. Vector search helps by:

• Grounding answers in your own, current data (RAG).
• Enabling semantic search, where "reset my login" can match an article titled "Recover your account access".
• Powering recommendations and deduplication using similarity between items.
• Giving agents long-term memory by storing and recalling past interactions.

A common reason teams choose Atlas for this is simplicity: one platform for operational data, metadata filters and vectors means fewer systems to sync and secure.

Choose Your Embeddings Approach

A vector index needs embeddings, which are lists of numbers that represent the meaning of text. You have three ways to get them:

This tutorial covers the first two in full and the third briefly. Automatic embedding is a newer Atlas feature, so confirm its availability for your cluster tier and region in the docs before relying on it.

Prerequisites

• A MongoDB Atlas account and a free (M0) cluster. The free tier supports Atlas Vector Search, with limits on the number of search indexes.
• Your IP address in the Atlas network access list and a database user.
• mongosh (a recent version) for Path A.
• Python 3.9 or later for Path B.
• No paid API key is needed.

Sample data. Both paths use a small collection of MongoDB concepts. Connect with mongosh and run:

Path A: Automatic Embeddings with Voyage AI (No Embedding Code)

With an autoEmbed field, you tell Atlas which text field to embed and which model to use. Atlas creates the vectors when it builds the index and keeps them in sync, and it embeds your query text at search time.

Step 1: Create the Vector Search Index

Use the createSearchIndexes command:

Notice that there is no numDimensions and no embedding code. Atlas handles both.

Step 2: Wait Until the Index Is Ready

Wait until the output shows queryable: true. The first build embeds every document, so it can take a minute or more.

Step 3: Search with Plain Text

Instead of a queryVector, pass the question as query.text:

Sample output (scores may vary slightly):

The top result is Sharding, even though the question never uses the word "shard". That is semantic search: the match is based on meaning, not keywords. Exact scores will vary with the model version.

Resources: MongoDB Docs, Automated Embedding for Atlas Vector Search; MongoDB Docs, $vectorSearch Aggregation Stage; MongoDB Docs, Voyage AI Text Embeddings.

Path B: Open-Source Embeddings with sentence-transformers

If you want full control, or want to run offline, generate the embeddings yourself with a free open-source model. This path uses all-MiniLM-L6-v2, which returns 384 dimensions and runs on a normal laptop CPU.

Step 1: Generate and Store Embeddings

For longer documents, split the text into chunks of a few hundred tokens with a little overlap and embed each chunk as its own document.

Step 2: Create the Vector Search Index

Three rules matter here:

• numDimensions must equal the length of your vectors exactly (384 for this model).
• Filter fields must be declared in the index with type: "filter" before you can use them in a query.
• Index builds are asynchronous. Wait until the index is queryable (collection.list_search_indexes("concepts_local_index") shows queryable: True) before searching.

Step 3: Query with $vectorSearch

Embed the question with the same model you used for the documents, then pass the vector to $vectorSearch:

Sample output (scores may vary slightly):

Note: small local models rank less precisely than larger hosted models, so scores and the order of close results can differ from Voyage. Atlas also rescales cosine scores to a 0 to 1 range, so they are higher than raw cosine values. If you need sharper ranking, ask a more specific question, or switch to a larger model such as all-mpnet-base-v2, which returns 768 dimensions, so update numDimensions to 768 and re-embed your data.

Optional: Using OpenAI Embeddings Instead

If you already have an OpenAI API key, only the embedding helper and the index dimensions change. The rest of Path B stays the same. Remember that the API generally needs prepaid credits.

text-embedding-3-small returns 1536 dimensions by default, so set numDimensions to 1536 in a new index and store the vectors in the embedding field. You cannot mix vectors from different models in one index, so re-embed your data if you switch models.

Resources: OpenAI Platform Docs, Embeddings guide.

Common Problems and How to Fix Them

These issues come up often in the MongoDB Community Forums and in the docs' troubleshooting notes.

1. $vectorSearch returns no results. Check that the index status is READY, that the index name in your query matches the real index name and that the path matches the field holding the embeddings.

2. Dimension mismatch. The numDimensions in the index must equal the length of your vectors. If you change the embedding model or the dimensions parameter, you need to re-embed your data and update the index.

3. Filter not working. The filter field must be indexed as a filter type in the vector index. Add it to the index definition and wait for the rebuild.

4. Results look irrelevant. Make sure you embed queries with the same model as the documents. Then review chunk size, add metadata filters and consider hybrid search.

5. Slow or memory-heavy queries on large collections. Review your numCandidates value, consider quantization and check that your cluster tier has enough memory for the search nodes or index size. The docs include guidance on sizing and dedicated Search Nodes.

6. "The maximum number of FTS indexes has been reached for this instance size." Free and small cluster tiers allow only a few search and vector search indexes per cluster, and the Atlas sample datasets can already use some of them. List your search indexes in the Atlas Search tab, then drop one you no longer need (in mongosh, for example, db.concepts.dropSearchIndex("concepts_vector_index")) or upgrade the cluster tier. In this tutorial's two paths you can build and test one index at a time, dropping the first before creating the second.

7. Empty results with no error. If $vectorSearch returns an empty array and no error, the index named in your query may not exist. Atlas does not raise an error for a missing index name. Run db.concepts.getSearchIndexes() and check that the index you are querying is listed with queryable: true. This often happens after dropping an index to stay under the free-tier limit.

Best Practices Checklist

• Use one embedding model consistently for both documents and queries.
• Chunk documents thoughtfully and store the source reference with each chunk.
• Declare filter fields in your index from the start.
• Store secrets in environment variables or a secrets manager.
• Evaluate retrieval quality with a small test set of real questions before tuning the LLM prompt.
• Monitor latency, index size and embedding costs as your data grows.

Conclusion

You can build working semantic search on MongoDB Atlas without paying for an embedding API. With autoEmbed, Atlas generates embeddings from Voyage AI models for you, and with sentence-transformers you generate them yourself. Either way, a vector index and a single $vectorSearch stage give you results based on meaning, which you can combine with filters, hybrid search and an LLM for RAG. Start with the free route, then move to a paid or larger model only if your quality or scale requirements call for it.