---
title: "Reference: MongoDB Vector Store | Vectors"
description: Documentation for the MongoDBVector class in Mastra, which provides vector search using MongoDB Atlas and Atlas Vector Search.
packages:
  - "@mastra/core"
  - "@mastra/fastembed"
  - "@mastra/memory"
  - "@mastra/mongodb"
---

# MongoDB Vector Store

The `MongoDBVector` class provides vector search using [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/). It enables efficient similarity search and metadata filtering within your MongoDB collections.

## Installation

```bash
npm install @mastra/mongodb@beta
```

## Usage Example

```typescript
import { MongoDBVector } from "@mastra/mongodb";

const store = new MongoDBVector({
  id: 'mongodb-vector',
  uri: process.env.MONGODB_URI,
  dbName: process.env.MONGODB_DATABASE,
});
```

## Constructor Options

<PropertiesTable
  content={[
    {
      name: "id",
      type: "string",
      description: "Unique identifier for this vector store instance",
    },
    {
      name: "uri",
      type: "string",
      description: "MongoDB connection string",
    },
    {
      name: "dbName",
      type: "string",
      description: "Name of the MongoDB database to use",
    },
    {
      name: "options",
      type: "MongoClientOptions",
      isOptional: true,
      description: "Optional MongoDB client options",
    },
  ]}
/>

## Methods

### createIndex()

Creates a new vector index (collection) in MongoDB.

<PropertiesTable
  content={[
    {
      name: "indexName",
      type: "string",
      description: "Name of the collection to create",
    },
    {
      name: "dimension",
      type: "number",
      description: "Vector dimension (must match your embedding model)",
    },
    {
      name: "metric",
      type: "'cosine' | 'euclidean' | 'dotproduct'",
      isOptional: true,
      defaultValue: "cosine",
      description: "Distance metric for similarity search",
    },
  ]}
/>

### upsert()

Adds or updates vectors and their metadata in the collection.

<PropertiesTable
  content={[
    {
      name: "indexName",
      type: "string",
      description: "Name of the collection to insert into",
    },
    {
      name: "vectors",
      type: "number[][]",
      description: "Array of embedding vectors",
    },
    {
      name: "metadata",
      type: "Record<string, any>[]",
      isOptional: true,
      description: "Metadata for each vector",
    },
    {
      name: "ids",
      type: "string[]",
      isOptional: true,
      description: "Optional vector IDs (auto-generated if not provided)",
    },
  ]}
/>

### query()

Searches for similar vectors with optional metadata filtering.

<PropertiesTable
  content={[
    {
      name: "indexName",
      type: "string",
      description: "Name of the collection to search in",
    },
    {
      name: "queryVector",
      type: "number[]",
      description: "Query vector to find similar vectors for",
    },
    {
      name: "topK",
      type: "number",
      isOptional: true,
      defaultValue: "10",
      description: "Number of results to return",
    },
    {
      name: "filter",
      type: "Record<string, any>",
      isOptional: true,
      description: "Metadata filters (applies to the `metadata` field)",
    },
    {
      name: "documentFilter",
      type: "Record<string, any>",
      isOptional: true,
      description: "Filters on original document fields (not just metadata)",
    },
    {
      name: "includeVector",
      type: "boolean",
      isOptional: true,
      defaultValue: "false",
      description: "Whether to include vector data in results",
    },
    {
      name: "minScore",
      type: "number",
      isOptional: true,
      defaultValue: "0",
      description: "Minimum similarity score threshold",
    },
  ]}
/>

### describeIndex()

Returns information about the index (collection).

<PropertiesTable
  content={[
    {
      name: "indexName",
      type: "string",
      description: "Name of the collection to describe",
    },
  ]}
/>

Returns:

```typescript
interface IndexStats {
  dimension: number;
  count: number;
  metric: "cosine" | "euclidean" | "dotproduct";
}
```

### deleteIndex()

Deletes a collection and all its data.

<PropertiesTable
  content={[
    {
      name: "indexName",
      type: "string",
      description: "Name of the collection to delete",
    },
  ]}
/>

### listIndexes()

Lists all vector collections in the MongoDB database.

Returns: `Promise<string[]>`

### updateVector()

Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.

<PropertiesTable
  content={[
    {
      name: "indexName",
      type: "string",
      description: "Name of the collection containing the vector",
    },
    {
      name: "id",
      type: "string",
      isOptional: true,
      description: "ID of the vector entry to update (mutually exclusive with filter)",
    },
    {
      name: "filter",
      type: "Record<string, any>",
      isOptional: true,
      description: "Metadata filter to identify vector(s) to update (mutually exclusive with id)",
    },
    {
      name: "update",
      type: "object",
      description: "Update data containing vector and/or metadata",
    },
    {
      name: "update.vector",
      type: "number[]",
      isOptional: true,
      description: "New vector data to update",
    },
    {
      name: "update.metadata",
      type: "Record<string, any>",
      isOptional: true,
      description: "New metadata to update",
    },
  ]}
/>

### deleteVector()

Deletes a specific vector entry from an index by its ID.

<PropertiesTable
  content={[
    {
      name: "indexName",
      type: "string",
      description: "Name of the collection containing the vector",
    },
    {
      name: "id",
      type: "string",
      description: "ID of the vector entry to delete",
    },
  ]}
/>

### deleteVectors()

Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.

<PropertiesTable
  content={[
    {
      name: "indexName",
      type: "string",
      description: "Name of the collection containing the vectors to delete",
    },
    {
      name: "ids",
      type: "string[]",
      isOptional: true,
      description: "Array of vector IDs to delete (mutually exclusive with filter)",
    },
    {
      name: "filter",
      type: "Record<string, any>",
      isOptional: true,
      description: "Metadata filter to identify vectors to delete (mutually exclusive with ids)",
    },
  ]}
/>

### disconnect()

Closes the MongoDB client connection. Should be called when done using the store.

## Response Types

Query results are returned in this format:

```typescript
interface QueryResult {
  id: string;
  score: number;
  metadata: Record<string, any>;
  vector?: number[]; // Only included if includeVector is true
}
```

## Error Handling

The store throws typed errors that can be caught:

```typescript
try {
  await store.query({
    indexName: "my_collection",
    queryVector: queryVector,
  });
} catch (error) {
  // Handle specific error cases
  if (error.message.includes("Invalid collection name")) {
    console.error(
      "Collection name must start with a letter or underscore and contain only valid characters.",
    );
  } else if (error.message.includes("Collection not found")) {
    console.error("The specified collection does not exist");
  } else {
    console.error("Vector store error:", error.message);
  }
}
```

## Best Practices

- Index metadata fields used in filters for optimal query performance.
- Use consistent field naming in metadata to avoid unexpected query results.
- Regularly monitor index and collection statistics to ensure efficient search.

## Usage Example

### Vector embeddings with MongoDB

Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords).

> Note: You must use a deployment hosted on MongoDB Atlas to successfully use the MongoDB Vector database.

This setup uses FastEmbed, a local embedding model, to generate vector embeddings.
To use this, install `@mastra/fastembed`:

```bash 
npm install @mastra/fastembed@beta
```

Add the following to your agent:

```typescript title="src/mastra/agents/example-mongodb-agent.ts"
import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { MongoDBStore, MongoDBVector } from "@mastra/mongodb";
import { fastembed } from "@mastra/fastembed";

export const mongodbAgent = new Agent({
  id: "mongodb-agent",
  name: "mongodb-agent",
  instructions:
    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
  model: "openai/gpt-5.1",
  memory: new Memory({
    storage: new MongoDBStore({
      id: 'mongodb-storage',
      uri: process.env.MONGODB_URI!,
      dbName: process.env.MONGODB_DB_NAME!,
    }),
    vector: new MongoDBVector({
      id: 'mongodb-vector',
      uri: process.env.MONGODB_URI!,
      dbName: process.env.MONGODB_DB_NAME!,
    }),
    embedder: fastembed,
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
      },
      generateTitle: true, // generates descriptive thread titles automatically
    },
  }),
});
```

## Related

- [Metadata Filters](../rag/metadata-filters)
