# 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

**npm**:

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

**pnpm**:

```bash
pnpm add @mastra/mongodb@latest
```

**Yarn**:

```bash
yarn add @mastra/mongodb@latest
```

**Bun**:

```bash
bun add @mastra/mongodb@latest
```

## 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,
});
```

### Custom Embedding Field Path

If you need to store embeddings in a nested field structure (e.g., to integrate with existing MongoDB collections), use the `embeddingFieldPath` option:

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

const store = new MongoDBVector({
  id: 'mongodb-vector',
  uri: process.env.MONGODB_URI,
  dbName: process.env.MONGODB_DATABASE,
  embeddingFieldPath: 'text.contentEmbedding', // Store embeddings at text.contentEmbedding
});
```

## Constructor Options

**id:** (`string`): Unique identifier for this vector store instance

**uri:** (`string`): MongoDB connection string

**dbName:** (`string`): Name of the MongoDB database to use

**options?:** (`MongoClientOptions`): Optional MongoDB client options

**embeddingFieldPath?:** (`string`): Path to the field that stores vector embeddings. Supports nested paths using dot notation (e.g., 'text.contentEmbedding'). (Default: `embedding`)

## Methods

### createIndex()

Creates a new vector index (collection) in MongoDB.

**indexName:** (`string`): Name of the collection to create

**dimension:** (`number`): Vector dimension (must match your embedding model)

**metric?:** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)

### upsert()

Adds or updates vectors and their metadata in the collection.

**indexName:** (`string`): Name of the collection to insert into

**vectors:** (`number[][]`): Array of embedding vectors

**metadata?:** (`Record<string, any>[]`): Metadata for each vector

**ids?:** (`string[]`): Optional vector IDs (auto-generated if not provided)

### query()

Searches for similar vectors with optional metadata filtering.

**indexName:** (`string`): Name of the collection to search in

**queryVector:** (`number[]`): Query vector to find similar vectors for

**topK?:** (`number`): Number of results to return (Default: `10`)

**filter?:** (`Record<string, any>`): Metadata filters (applies to the \`metadata\` field)

**documentFilter?:** (`Record<string, any>`): Filters on original document fields (not just metadata)

**includeVector?:** (`boolean`): Whether to include vector data in results (Default: `false`)

**minScore?:** (`number`): Minimum similarity score threshold (Default: `0`)

### describeIndex()

Returns information about the index (collection).

**indexName:** (`string`): 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.

**indexName:** (`string`): 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.

**indexName:** (`string`): Name of the collection containing the vector

**id?:** (`string`): ID of the vector entry to update (mutually exclusive with filter)

**filter?:** (`Record<string, any>`): Metadata filter to identify vector(s) to update (mutually exclusive with id)

**update:** (`object`): Update data containing vector and/or metadata

**update.vector?:** (`number[]`): New vector data to update

**update.metadata?:** (`Record<string, any>`): New metadata to update

### deleteVector()

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

**indexName:** (`string`): Name of the collection containing the vector

**id:** (`string`): 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.

**indexName:** (`string`): Name of the collection containing the vectors to delete

**ids?:** (`string[]`): Array of vector IDs to delete (mutually exclusive with filter)

**filter?:** (`Record<string, any>`): 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`:

**npm**:

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

**pnpm**:

```bash
pnpm add @mastra/fastembed@latest
```

**Yarn**:

```bash
yarn add @mastra/fastembed@latest
```

**Bun**:

```bash
bun add @mastra/fastembed@latest
```

Add the following to your agent:

```typescript
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](https://mastra.ai/reference/rag/metadata-filters)