MongoDB Atlas Vector Search

MongoDB Atlas vector search integration

Overview

MongoDB Atlas Vector Search provides native vector search capabilities within MongoDB Atlas, combining document storage with vector similarity search.

Installation

npm install @llamaindex/mongodb mongodb

Basic Usage

import { MongoDBAtlasVectorSearch } from "@llamaindex/mongodb";
import { VectorStoreIndex, Document } from "llamaindex";

const vectorStore = new MongoDBAtlasVectorSearch({
  dbName: "my_database",
  collectionName: "embeddings"
});

const documents = [
  new Document({ text: "LlamaIndex is a data framework." }),
  new Document({ text: "MongoDB is a document database." })
];

const index = await VectorStoreIndex.fromDocuments(documents, {
  storageContext: { vectorStore }
});

const queryEngine = index.asQueryEngine();
const response = await queryEngine.query({
  query: "What is MongoDB?"
});

Constructor Options

dbName · string · required

MongoDB database name

collectionName · string · required

MongoDB collection name for storing vectors

mongodbClient · MongoClient

MongoDB client instance. If not provided, creates client using MONGODB_URI env var

indexName · string · default: "default"

Name of the vector search index

embeddingKey · string · default: "embedding"

Field name for storing embedding vectors

textKey · string · default: "text"

Field name for storing text content

idKey · string · default: "id"

Field name for storing node IDs

metadataKey · string · default: "metadata"

Field name for storing metadata

autoCreateIndex · boolean · default: true

Automatically create vector search index if it doesn’t exist

indexedMetadataFields · string[] · default: []

List of metadata fields to index for filtering

embeddingDefinition · object

Custom embedding configuration. Default: {type: "knnVector", dimensions: 1536, similarity: "cosine"}

numCandidates · (query) => number

Function to determine number of candidates for search. Default: similarityTopK * 10

Configuration

Environment Variables

MONGODB_URI=mongodb+srv://username:[e-mail]/

With Custom Client

import { MongoClient } from "mongodb";
import { MongoDBAtlasVectorSearch } from "@llamaindex/mongodb";

const client = new MongoClient("mongodb+srv://...");
await client.connect();

const vectorStore = new MongoDBAtlasVectorSearch({
  mongodbClient: client,
  dbName: "my_database",
  collectionName: "embeddings"
});

Setting Up MongoDB Atlas

Create Atlas Search Index

1. Go to your MongoDB Atlas cluster
2. Navigate to the “Search” tab
3. Click “Create Search Index”
4. Use JSON editor and configure:

{
  "mappings": {
    "dynamic": true,
    "fields": {
      "embedding": {
        "type": "knnVector",
        "dimensions": 1536,
        "similarity": "cosine"
      }
    }
  }
}

Or let the vector store auto-create the index:

const vectorStore = new MongoDBAtlasVectorSearch({
  dbName: "my_database",
  collectionName: "embeddings",
  autoCreateIndex: true,  // Creates index automatically
  embeddingDefinition: {
    type: "knnVector",
    dimensions: 1536,
    similarity: "cosine"
  }
});

Querying

Basic Query

const index = await VectorStoreIndex.fromVectorStore(vectorStore);

const retriever = index.asRetriever({
  similarityTopK: 5
});

const nodes = await retriever.retrieve("query text");

nodes.forEach(node => {
  console.log(`Score: ${node.score}`);
  console.log(`Text: ${node.node.text}`);
});

Metadata Filtering

import { MetadataFilters, FilterCondition } from "@llamaindex/core/vector-store";

const vectorStore = new MongoDBAtlasVectorSearch({
  dbName: "my_database",
  collectionName: "embeddings",
  indexedMetadataFields: ["category", "year"]  // Index these fields
});

const documents = [
  new Document({
    text: "Doc 1",
    metadata: { category: "tech", year: 2023 }
  }),
  new Document({
    text: "Doc 2",
    metadata: { category: "science", year: 2024 }
  })
];

const index = await VectorStoreIndex.fromDocuments(documents, {
  storageContext: { vectorStore }
});

const retriever = index.asRetriever({
  filters: new MetadataFilters({
    filters: [
      { key: "category", value: "tech", operator: "==" },
      { key: "year", value: 2023, operator: ">=" }
    ],
    condition: FilterCondition.AND
  })
});

const nodes = await retriever.retrieve("query");

Supported Filter Operators

MongoDB Atlas Vector Search supports:

• == - Equal
• != - Not equal
• < - Less than
• <= - Less than or equal
• > - Greater than
• >= - Greater than or equal
• in - Value in array
• nin - Value not in array

Managing Data

Add Documents

const newDoc = new Document({ text: "New content" });
await index.insert(newDoc);

Delete by Document ID

await vectorStore.delete(refDocId);

Access MongoDB Client

const client = vectorStore.client();
const collection = await vectorStore.ensureCollection();

// Perform MongoDB operations
const count = await collection.countDocuments();
console.log("Total documents:", count);

Advanced Configuration

Custom Number of Candidates

const vectorStore = new MongoDBAtlasVectorSearch({
  dbName: "my_database",
  collectionName: "embeddings",
  numCandidates: (query) => query.similarityTopK * 20  // More candidates
});

Multiple Indexed Metadata Fields

const vectorStore = new MongoDBAtlasVectorSearch({
  dbName: "my_database",
  collectionName: "embeddings",
  indexedMetadataFields: ["category", "author", "tags", "date"],
  autoCreateIndex: true
});

Complete Example

import { MongoDBAtlasVectorSearch } from "@llamaindex/mongodb";
import { VectorStoreIndex, Document, Settings } from "llamaindex";
import { OpenAI, OpenAIEmbedding } from "@llamaindex/openai";

// Configure settings
Settings.llm = new OpenAI({ model: "gpt-4" });
Settings.embedModel = new OpenAIEmbedding();

// Create vector store
const vectorStore = new MongoDBAtlasVectorSearch({
  dbName: "llamaindex_db",
  collectionName: "documents",
  indexName: "vector_index",
  indexedMetadataFields: ["source", "category"],
  autoCreateIndex: true
});

// Load documents
const documents = [
  new Document({
    text: "MongoDB Atlas provides vector search...",
    metadata: { source: "docs", category: "database" }
  }),
  new Document({
    text: "LlamaIndex integrates with MongoDB...",
    metadata: { source: "tutorial", category: "integration" }
  })
];

// Build index
const index = await VectorStoreIndex.fromDocuments(documents, {
  storageContext: { vectorStore }
});

// Query with filters
const retriever = index.asRetriever({
  similarityTopK: 3,
  filters: new MetadataFilters({
    filters: [{ key: "category", value: "database", operator: "==" }]
  })
});

const nodes = await retriever.retrieve("vector search");
console.log(nodes);

Best Practices

1. Index metadata fields: Only index fields you’ll filter on
2. Match dimensions: Ensure embedding dimensions match your model
3. Use auto-create: Let the store manage index creation
4. Tune candidates: Adjust numCandidates for performance vs accuracy
5. Monitor costs: Track Atlas usage and storage
6. Use connection pooling: Reuse MongoDB client instances

Troubleshooting

Index Not Found

If you see errors about missing index:

// Enable auto-create
const vectorStore = new MongoDBAtlasVectorSearch({
  dbName: "my_database",
  collectionName: "embeddings",
  autoCreateIndex: true
});

Dimension Mismatch

Ensure your embedding model matches the index configuration:

import { OpenAIEmbedding } from "@llamaindex/openai";

// text-embedding-3-small: 1536 dimensions
const embedModel = new OpenAIEmbedding({
  model: "text-embedding-3-small"
});

// MongoDB index must match
const vectorStore = new MongoDBAtlasVectorSearch({
  dbName: "my_database",
  collectionName: "embeddings",
  embeddingDefinition: {
    type: "knnVector",
    dimensions: 1536,
    similarity: "cosine"
  }
});

See Also

• MongoDB Atlas Vector Search Documentation
• Vector Store Index
• Core Schema