Vector search and embeddings in MongoDB

This chapter follows Full-text search in MongoDB. Embeddings are dense numeric vectors that capture meaning; similar text produces vectors that are close under cosine or dot product distance.

MongoDB Vector Search stores vectors in documents and queries them with $vectorSearch (Atlas and Atlas Local). MongoDB’s Voyage AI integration recommends models such as voyage-4, voyage-4-large, and voyage-4-lite; voyage-3-large remains common in samples with 1024 default dimensions (256, 512, 2048 also supported on several models).

Generate embeddings with Voyage AI

Obtain an API key from Voyage AI or Atlas Embedding API. Use input_type document when indexing and query when searching for best retrieval quality.

1
const VOYAGE_URL = 'https://api.voyageai.com/v1/embeddings';
2

3
export async function embedTexts(
4
  texts: string[],
5
  inputType: 'query' | 'document',
6
  model = 'voyage-4',
7
): Promise<number[][]> {
8
  const res = await fetch(VOYAGE_URL, {
9
    method: 'POST',
10
    headers: {
11
      'Content-Type': 'application/json',
12
      Authorization: `Bearer ${process.env.VOYAGE_API_KEY}`,
13
    },
14
    body: JSON.stringify({
15
      input: texts,
16
      model,
17
      input_type: inputType,
18
      output_dimension: 1024,
19
    }),
20
  });
21
  if (!res.ok) throw new Error(await res.text());
22
  const json = (await res.json()) as { data: { embedding: number[] }[] };
23
  return json.data.map((d) => d.embedding);
24
}

Store vectors in documents

1
interface ArticleChunk {
2
  articleId: string;
3
  text: string;
4
  embedding: number[];
5
}
6

7
await chunks.insertOne({
8
  articleId: 'intro-mongodb',
9
  text: 'Replica sets provide automatic failover.',
10
  embedding: (await embedTexts(['Replica sets provide automatic failover.'], 'document'))[0],
11
});

Atlas also supports automated embedding fields (autoEmbed) that call Voyage on insert—see MongoDB docs for self-managed mongot configuration.

Vector search index

Index definition must match vector length and similarity:

1
{
2
  "fields": [
3
    {
4
      "type": "vector",
5
      "path": "embedding",
6
      "numDimensions": 1024,
7
      "similarity": "dotProduct"
8
    },
9
    {
10
      "type": "filter",
11
      "path": "articleId"
12
    }
13
  ]
14
}

Create via createSearchIndex with type: 'vectorSearch'.

$vectorSearch stage

1
db.chunks.aggregate([
2
  {
3
    $vectorSearch: {
4
      index: 'chunks_vector',
5
      path: 'embedding',
6
      queryVector: queryEmbedding,
7
      numCandidates: 150,
8
      limit: 10,
9
      filter: { articleId: { $eq: 'intro-mongodb' } },
10
    },
11
  },
12
  {
13
    $project: {
14
      text: 1,
15
      score: { $meta: 'vectorSearchScore' },
16
    },
17
  },
18
])

numCandidates trades recall for speed (ANN search). Increase for harder queries.

Hybrid search with $rankFusion

Combine lexical $search and $vectorSearch ranks:

1
[
2
  {
3
    $rankFusion: {
4
      input: {
5
        pipelines: {
6
          fullText: [
7
            { $search: { index: 'articles_search', text: { query: userQuery, path: 'body' } } },
8
            { $limit: 50 },
9
          ],
10
          semantic: [
11
            {
12
              $vectorSearch: {
13
                index: 'chunks_vector',
14
                path: 'embedding',
15
                queryVector: queryEmbedding,
16
                numCandidates: 100,
17
                limit: 50,
18
              },
19
            },
20
          ],
21
        },
22
      },
23
    },
24
  },
25
  { $limit: 10 },
26
]

Availability depends on cluster version and Search deployment; verify on your Atlas tier or Atlas Local version.

RAG retrieval sketch

1
import { Db } from 'mongodb';
2
import { embedTexts } from '../embeddings/voyage.js';
3

4
export async function retrieveContext(db: Db, question: string, limit = 5) {
5
  const [queryVector] = await embedTexts([question], 'query');
6
  return db.collection('chunks').aggregate([
7
    {
8
      $vectorSearch: {
9
        index: 'chunks_vector',
10
        path: 'embedding',
11
        queryVector: queryVector,
12
        numCandidates: 100,
13
        limit,
14
      },
15
    },
16
    { $project: { text: 1, score: { $meta: 'vectorSearchScore' } } },
17
  ]).toArray();
18
}

Pass returned text fields to your LLM as context—not as trusted instructions.

Next: MongoDB cheat sheet.

Vector search and embeddings in MongoDB

Generate embeddings with Voyage AI

Store vectors in documents

Vector search index

$vectorSearch stage

Hybrid search with $rankFusion

RAG retrieval sketch

Check your understanding

Search articles