@mastra/mongodb 1.12.1 → 1.13.0

package/dist/docs/references/reference-storage-mongodb.md

@@ -32,7 +32,7 @@ bun add @mastra/mongodb@latest
 
 ## Usage
 
-Ensure you have a MongoDB Atlas Local (via Docker) or MongoDB Atlas Cloud instance with Atlas Search enabled. MongoDB 7.0+ is recommended.
+Ensure you have a [MongoDB Atlas Local (via Docker)](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/) or [MongoDB Atlas Cloud](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-getting-started/) instance with Atlas Search enabled. MongoDB 7.0+ is recommended.
 
 ```typescript
 import { MongoDBStore } from '@mastra/mongodb'
@@ -40,7 +40,7 @@ import { MongoDBStore } from '@mastra/mongodb'
 const storage = new MongoDBStore({
   id: 'mongodb-storage',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 ```
 
@@ -54,7 +54,15 @@ const storage = new MongoDBStore({
 
 **dbName** (`string`): The name of the database you want the storage to use.
 
-**options** (`MongoClientOptions`): MongoDB client options for advanced configuration (SSL, connection pooling, etc.).
+**options** (`MongoClientOptions`): MongoDB client options for advanced configuration (SSL, connection pooling, etc.). See Connection Options
+
+**disableInit** (`boolean`): When true, automatic initialization (collection creation) is disabled. Useful for CI/CD pipelines where you want to run migrations explicitly. You must call storage.init() manually when this is true.
+
+**skipDefaultIndexes** (`boolean`): When true, default indexes will not be created during initialization. Useful when managing indexes separately or using only custom indexes.
+
+**indexes** (`MongoDBIndexConfig[]`): Custom indexes to create during initialization. Each index must specify a collection, keys, and optional index options. See Indexes
+
+**connectorHandler** (`ConnectorHandler`): Custom connection handler for advanced connection management. Alternative to providing uri/dbName directly.
 
 > **Deprecation Notice:** The `url` parameter is deprecated but still supported for backward compatibility. Please use `uri` instead in all new code.
 
@@ -84,6 +92,26 @@ const store2 = new MongoDBStore({
     socketTimeoutMS: 45000,
   },
 })
+
+// With custom indexes
+const store3 = new MongoDBStore({
+  id: 'mongodb-storage-03',
+  uri: 'mongodb+srv://user:password@cluster.mongodb.net',
+  dbName: 'mastra_storage',
+  indexes: [
+    { collection: 'mastra_threads', keys: { 'metadata.type': 1 } },
+    { collection: 'mastra_messages', keys: { 'metadata.status': 1 }, options: { sparse: true } },
+  ],
+})
+
+// For CI/CD with explicit initialization
+const store4 = new MongoDBStore({
+  id: 'mongodb-storage-04',
+  uri: 'mongodb+srv://user:password@cluster.mongodb.net',
+  dbName: 'mastra_storage',
+  disableInit: true, // Disable auto-init
+})
+await store4.init() // Call init explicitly
 ```
 
 ## Additional notes
@@ -114,7 +142,7 @@ import { MongoDBStore } from '@mastra/mongodb'
 const storage = new MongoDBStore({
   id: 'mongodb-storage',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 
 const mastra = new Mastra({
@@ -130,7 +158,7 @@ import { MongoDBStore } from '@mastra/mongodb'
 const storage = new MongoDBStore({
   id: 'mongodb-storage',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 
 // Required when using storage directly
@@ -143,57 +171,28 @@ const thread = await memoryStore?.getThreadById({ threadId: '...' })
 
 > **Warning:** If `init()` isn't called, collections won't be created and storage operations will fail silently or throw errors.
 
-## Vector search capabilities
-
-MongoDB storage includes built-in vector search capabilities for AI applications:
+### Connection Management
 
-### Vector Index Creation
+The `close()` method closes the MongoDB client connection. Call this when shutting down your application:
 
 ```typescript
-import { MongoDBVector } from '@mastra/mongodb'
+import { MongoDBStore } from '@mastra/mongodb'
 
-const vectorStore = new MongoDBVector({
-  id: 'mongodb-vector',
+const storage = new MongoDBStore({
+  id: 'mongodb-storage',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 
-// Create a vector index for embeddings
-await vectorStore.createIndex({
-  indexName: 'document_embeddings',
-  dimension: 1536,
-})
+// Use storage...
+
+// Clean up on shutdown
+await storage.close()
 ```
 
-### Vector Operations
+## Vector search capabilities
 
-```typescript
-// Store vectors with metadata
-await vectorStore.upsert({
-  indexName: "document_embeddings",
-  vectors: [
-    {
-      id: "doc-1",
-      values: [0.1, 0.2, 0.3, ...], // 1536-dimensional vector
-      metadata: {
-        title: "Document Title",
-        category: "technical",
-        source: "api-docs",
-      },
-    },
-  ],
-});
-
-// Similarity search
-const results = await vectorStore.query({
-  indexName: "document_embeddings",
-  vector: queryEmbedding,
-  topK: 5,
-  filter: {
-    category: "technical",
-  },
-});
-```
+MongoDB storage includes built-in vector search capabilities for AI applications. For detailed vector operations including index creation, upserting embeddings, similarity search, and metadata filtering, see the [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb).
 
 ## Usage example
 
@@ -214,6 +213,7 @@ export const mongodbAgent = new Agent({
   model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new MongoDBStore({
+      id: 'mongodb-storage',
       uri: process.env.MONGODB_URI!,
       dbName: process.env.MONGODB_DB_NAME!,
     }),

package/dist/docs/references/reference-vectors-mongodb.md

@@ -38,7 +38,7 @@ import { MongoDBVector } from '@mastra/mongodb'
 const store = new MongoDBVector({
   id: 'mongodb-vector',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 ```
 
@@ -52,7 +52,7 @@ import { MongoDBVector } from '@mastra/mongodb'
 const store = new MongoDBVector({
   id: 'mongodb-vector',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
   embeddingFieldPath: 'text.contentEmbedding', // Store embeddings at text.contentEmbedding
 })
 ```
@@ -71,6 +71,14 @@ const store = new MongoDBVector({
 
 ## Methods
 
+### `connect()`
+
+Establishes connection to the MongoDB server. This is called automatically on first use, but can be called explicitly if needed.
+
+```typescript
+await store.connect()
+```
+
 ### `createIndex()`
 
 Creates a new vector index (collection) in MongoDB.
@@ -81,6 +89,16 @@ Creates a new vector index (collection) in MongoDB.
 
 **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
 
+### `waitForIndexReady()`
+
+Waits for an index to become ready after creation. Useful when you need to ensure an index is ready before performing operations.
+
+**indexName** (`string`): Name of the index to wait for
+
+**timeoutMs** (`number`): Maximum time to wait in milliseconds (Default: `60000`)
+
+**checkIntervalMs** (`number`): Interval between status checks in milliseconds (Default: `2000`)
+
 ### `upsert()`
 
 Adds or updates vectors and their metadata in the collection.
@@ -93,6 +111,8 @@ Adds or updates vectors and their metadata in the collection.
 
 **ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
 
+**documents** (`string[]`): Optional document text content to store alongside vectors
+
 ### `query()`
 
 Searches for similar vectors with optional metadata filtering.
@@ -109,6 +129,8 @@ Searches for similar vectors with optional metadata filtering.
 
 **includeVector** (`boolean`): Whether to include vector data in results (Default: `false`)
 
+**numCandidates** (`number`): Number of candidates the HNSW graph considers before selecting top-K results. Higher values improve recall at the cost of latency. See: https\://www\.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/ (Default: `20 * topK (capped at 10000)`)
+
 ### `describeIndex()`
 
 Returns information about the index (collection).
@@ -224,7 +246,7 @@ try {
 
 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.
+> **Note:** MongoDB Atlas Vector Search is recommended for production use. For self-hosted deployments, Vector Search is available with [local Atlas deployments via the Atlas CLI](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-local/).
 
 This setup uses FastEmbed, a local embedding model, to generate vector embeddings. To use this, install `@mastra/fastembed`:
 
@@ -290,6 +312,73 @@ export const mongodbAgent = new Agent({
 })
 ```
 
+### Vector embeddings with VoyageAI
+
+VoyageAI provides specialized embedding models optimized for retrieval tasks. VoyageAI is also integrated with MongoDB Atlas for multimodal embeddings.
+
+**npm**:
+
+```bash
+npm install @mastra/voyageai@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/voyageai@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/voyageai@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/voyageai@latest
+```
+
+Basic usage example:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
+import { voyage } from '@mastra/voyageai'
+
+export const mongodbVoyageAgent = new Agent({
+  id: 'mongodb-voyage-agent',
+  name: 'MongoDB VoyageAI Agent',
+  instructions: 'You are an AI agent with semantic recall powered by VoyageAI and MongoDB.',
+  model: 'openai/gpt-5.5',
+  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: voyage, // VoyageAI's default model (voyage-3.5, 1024 dimensions)
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 5,
+        messageRange: 2,
+      },
+    },
+  }),
+})
+```
+
+For comprehensive VoyageAI embedding examples including specialized models, multimodal embeddings, and retrieval optimization, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings).
+
 ## Related
 
-- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
+- [VoyageAI Embeddings Documentation](https://mastra.ai/models/embeddings)

package/dist/index.cjs

@@ -15,7 +15,7 @@ var skills = require('@mastra/core/storage/domains/skills');
 
 // package.json
 var package_default = {
-  version: "1.12.1"};
+  version: "1.13.0"};
 var MongoDBFilterTranslator = class extends filter.BaseFilterTranslator {
   getSupportedOperators() {
     return {
@@ -2218,6 +2218,11 @@ var MongoDBDatasetsStorage = class extends storage.DatasetsStorage {
         keys: { datasetId: 1, datasetVersion: 1 },
         options: { name: "idx_dataset_items_datasetid_version" }
       },
+      {
+        collection: storage.TABLE_DATASET_ITEMS,
+        keys: { datasetId: 1, externalId: 1, datasetVersion: 1 },
+        options: { name: "idx_dataset_items_datasetid_externalid_version", sparse: true }
+      },
       {
         collection: storage.TABLE_DATASET_ITEMS,
         keys: { datasetId: 1, validTo: 1, isDeleted: 1, createdAt: -1, id: 1 },
@@ -2288,6 +2293,7 @@ var MongoDBDatasetsStorage = class extends storage.DatasetsStorage {
       id: row.id,
       datasetId: row.datasetId,
       datasetVersion: row.datasetVersion,
+      externalId: row.externalId ?? null,
       organizationId: row.organizationId ?? null,
       projectId: row.projectId ?? null,
       input: typeof row.input === "string" ? storage.safelyParseJSON(row.input) : row.input,
@@ -2319,7 +2325,8 @@ var MongoDBDatasetsStorage = class extends storage.DatasetsStorage {
   // --- Dataset CRUD ---
   async createDataset(input) {
     try {
-      const id = crypto$1.randomUUID();
+      const id = input.id ?? crypto$1.randomUUID();
+      if (input.id !== void 0) this.validateCallerDefinedDatasetId(input.id);
       const now = /* @__PURE__ */ new Date();
       const collection = await this.getCollection(storage.TABLE_DATASETS);
       const record = {
@@ -2344,6 +2351,10 @@ var MongoDBDatasetsStorage = class extends storage.DatasetsStorage {
       await collection.insertOne(record);
       return this.transformDatasetRow(record);
     } catch (error$1) {
+      if (input.id !== void 0 && storage.hasErrorCode(error$1, /* @__PURE__ */ new Set([11e3]))) {
+        const existing = await this.getDatasetById({ id: input.id });
+        if (existing) return this.resolveExistingDataset(existing, { ...input, id: input.id });
+      }
       if (error$1 instanceof error.MastraError) throw error$1;
       throw new error.MastraError(
         {
@@ -2657,6 +2668,7 @@ var MongoDBDatasetsStorage = class extends storage.DatasetsStorage {
             id: args.id,
             datasetId: args.datasetId,
             datasetVersion: newVersion,
+            externalId: existing.externalId ?? null,
             organizationId: parentOrganizationId,
             projectId: parentProjectId,
             validTo: null,
@@ -2753,6 +2765,7 @@ var MongoDBDatasetsStorage = class extends storage.DatasetsStorage {
             id,
             datasetId,
             datasetVersion: newVersion,
+            externalId: existing.externalId ?? null,
             organizationId: parentOrganizationId,
             projectId: parentProjectId,
             validTo: null,
@@ -2794,37 +2807,27 @@ var MongoDBDatasetsStorage = class extends storage.DatasetsStorage {
   // --- Batch operations ---
   async _doBatchInsertItems(input) {
     try {
-      const dataset = await this.getDatasetById({ id: input.datasetId });
-      if (!dataset) {
+      if (input.items.length === 0) return [];
+      const externalIds = [...new Set(input.items.flatMap((item) => item.externalId ? [item.externalId] : []))];
+      if (externalIds.length > 0 && !await this.#connector.supportsTransactions()) {
         throw new error.MastraError({
-          id: storage.createStorageErrorId("MONGODB", "BULK_ADD_ITEMS", "DATASET_NOT_FOUND"),
+          id: "DATASET_ITEM_IDENTITY_REQUIRES_TRANSACTIONS",
           domain: error.ErrorDomain.STORAGE,
           category: error.ErrorCategory.USER,
           details: { datasetId: input.datasetId }
         });
       }
-      if (!input.items || input.items.length === 0) {
-        return [];
-      }
-      const now = /* @__PURE__ */ new Date();
-      const versionId = crypto$1.randomUUID();
-      const itemsWithIds = input.items.map((itemInput) => ({
-        generatedId: crypto$1.randomUUID(),
-        itemInput
-      }));
       const datasetsCollection = await this.getCollection(storage.TABLE_DATASETS);
       const itemsCollection = await this.getCollection(storage.TABLE_DATASET_ITEMS);
       const versionsCollection = await this.getCollection(storage.TABLE_DATASET_VERSIONS);
-      let newVersion = 0;
-      let organizationId = null;
-      let projectId = null;
+      let resolvedItems = [];
       await this.#connector.withTransaction(async (session) => {
-        const result = await datasetsCollection.findOneAndUpdate(
+        const dataset = await datasetsCollection.findOneAndUpdate(
           { id: input.datasetId },
-          { $inc: { version: 1 } },
+          { $inc: { identityRevision: 1 } },
           { session, returnDocument: "after" }
         );
-        if (!result) {
+        if (!dataset) {
           throw new error.MastraError({
             id: storage.createStorageErrorId("MONGODB", "BULK_ADD_ITEMS", "DATASET_NOT_FOUND"),
             domain: error.ErrorDomain.STORAGE,
@@ -2832,54 +2835,52 @@ var MongoDBDatasetsStorage = class extends storage.DatasetsStorage {
             details: { datasetId: input.datasetId }
           });
         }
-        newVersion = result.version;
-        organizationId = result.organizationId ?? null;
-        projectId = result.projectId ?? null;
-        const docs = itemsWithIds.map(({ generatedId, itemInput }) => ({
-          id: generatedId,
-          datasetId: input.datasetId,
-          datasetVersion: newVersion,
-          organizationId,
-          projectId,
-          validTo: null,
-          isDeleted: false,
-          input: itemInput.input,
-          groundTruth: itemInput.groundTruth ?? null,
-          expectedTrajectory: itemInput.expectedTrajectory ?? null,
-          toolMocks: itemInput.toolMocks ?? null,
-          requestContext: itemInput.requestContext ?? null,
-          metadata: itemInput.metadata ?? null,
-          source: itemInput.source ?? null,
-          createdAt: now,
-          updatedAt: now
-        }));
-        await itemsCollection.insertMany(docs, { session });
-        await versionsCollection.insertOne(
-          {
-            id: versionId,
-            datasetId: input.datasetId,
-            version: newVersion,
-            createdAt: now
-          },
-          { session }
+        const historyRows = externalIds.length === 0 ? [] : await itemsCollection.find({ datasetId: input.datasetId, externalId: { $in: externalIds } }, { session }).sort({ datasetVersion: 1 }).toArray();
+        const plan = this.planDatasetItemBatch(
+          input.items,
+          historyRows.map((row) => this.transformItemRowFull(row)),
+          crypto$1.randomUUID
+        );
+        const resolved = new Map(
+          [...plan.existingCurrentItems].map(([id, row]) => [id, this.datasetItemFromRow(row)])
         );
+        if (plan.inserts.length > 0) {
+          const now = /* @__PURE__ */ new Date();
+          const newVersion = Number(dataset.version) + 1;
+          await datasetsCollection.updateOne(
+            { id: input.datasetId },
+            { $set: { version: newVersion, updatedAt: now } },
+            { session }
+          );
+          for (const insert of plan.inserts) {
+            const item = {
+              id: insert.id,
+              datasetId: input.datasetId,
+              datasetVersion: newVersion,
+              externalId: insert.item.externalId ?? null,
+              organizationId: dataset.organizationId ?? null,
+              projectId: dataset.projectId ?? null,
+              input: insert.item.input,
+              groundTruth: insert.item.groundTruth,
+              expectedTrajectory: insert.item.expectedTrajectory,
+              toolMocks: insert.item.toolMocks,
+              requestContext: insert.item.requestContext,
+              metadata: insert.item.metadata,
+              source: insert.item.source,
+              createdAt: now,
+              updatedAt: now
+            };
+            await itemsCollection.insertOne({ ...item, validTo: null, isDeleted: false }, { session });
+            resolved.set(item.id, item);
+          }
+          await versionsCollection.insertOne(
+            { id: crypto$1.randomUUID(), datasetId: input.datasetId, version: newVersion, createdAt: now },
+            { session }
+          );
+        }
+        resolvedItems = plan.resolvedIds.map((id) => resolved.get(id));
       });
-      return itemsWithIds.map(({ generatedId, itemInput }) => ({
-        id: generatedId,
-        datasetId: input.datasetId,
-        datasetVersion: newVersion,
-        organizationId,
-        projectId,
-        input: itemInput.input,
-        groundTruth: itemInput.groundTruth,
-        expectedTrajectory: itemInput.expectedTrajectory,
-        toolMocks: itemInput.toolMocks,
-        requestContext: itemInput.requestContext,
-        metadata: itemInput.metadata,
-        source: itemInput.source,
-        createdAt: now,
-        updatedAt: now
-      }));
+      return resolvedItems;
     } catch (error$1) {
       if (error$1 instanceof error.MastraError) throw error$1;
       throw new error.MastraError(
@@ -2938,6 +2939,7 @@ var MongoDBDatasetsStorage = class extends storage.DatasetsStorage {
           id: item.id,
           datasetId: input.datasetId,
           datasetVersion: newVersion,
+          externalId: item.externalId ?? null,
           organizationId: parentOrganizationId,
           projectId: parentProjectId,
           validTo: null,