@mastra/mongodb 1.18.10-alpha.0 → 1.19.0-alpha.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-mongodb
 description: Documentation for @mastra/mongodb. Use when working with @mastra/mongodb APIs, configuration, or implementation.
 metadata:
   package: "@mastra/mongodb"
-  version: "1.18.10-alpha.0"
+  version: "1.19.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.18.10-alpha.0",
+  "version": "1.19.0-alpha.0",
   "package": "@mastra/mongodb",
   "exports": {},
   "modules": {}

package/dist/docs/references/reference-rag-vector-databases.md

@@ -54,6 +54,29 @@ const results = await store.hybridQuery({
 
 See the [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb) for details on `createSearchIndex()`, `textQuery()`, and `hybridQuery()`.
 
+### Automated Embedding
+
+MongoDB can generate the embeddings itself, so you don't need an embedding provider in your application. Create the index with `autoEmbed` and a Voyage AI model, write plain text, and search with a query string:
+
+```ts
+await store.createIndex({
+  indexName: 'myCollection',
+  autoEmbed: { model: 'voyage-4' },
+})
+await store.upsert({
+  indexName: 'myCollection',
+  documents: chunks.map(chunk => chunk.text),
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
+const results = await store.query({
+  indexName: 'myCollection',
+  queryText: 'search terms',
+  topK: 10,
+})
+```
+
+Automated Embedding is a MongoDB Preview feature and needs a deployment where it's available. See the [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb) for the supported options and requirements.
+
 **PgVector**:
 
 ```ts

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

@@ -87,7 +87,9 @@ 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)
+**dimension** (`number`): Vector dimension (must match your embedding model). Required unless autoEmbed is set, where the embedding model determines the dimension. Passing both is an error.
+
+**autoEmbed** (`MongoDBAutoEmbedConfig`): Generate the embeddings in MongoDB instead of supplying vectors. See Automated Embedding for the supported fields.
 
 **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
 
@@ -115,13 +117,13 @@ Adds or updates vectors and their metadata in the collection. On a bring-your-ow
 
 **indexName** (`string`): Name of the collection to insert into
 
-**vectors** (`number[][]`): Array of embedding vectors
+**vectors** (`number[][]`): Array of embedding vectors. Required unless the index was created with autoEmbed, where MongoDB generates them from documents and supplying vectors is an error.
 
 **metadata** (`Record<string, any>[]`): Metadata for each vector
 
 **ids** (`string[]`): Optional vector IDs (auto-generated if not provided)
 
-**documents** (`string[]`): Optional document text content to store alongside vectors
+**documents** (`string[]`): Document text content to store alongside vectors. On an autoEmbed index this is the text MongoDB embeds, and it is required.
 
 ### `query()`
 
@@ -129,7 +131,11 @@ 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
+**queryVector** (`number[]`): Query vector to find similar vectors for. Supply this or queryText, not both.
+
+**queryText** (`string`): Text for MongoDB to embed at query time. autoEmbed indexes only, and mutually exclusive with queryVector. For full-text matching use textQuery() instead.
+
+**model** (`string`): Embedding model for this query, overriding the index's. Requires queryText, and must be compatible with the index's model.
 
 **topK** (`number`): Number of results to return (Default: `10`)
 
@@ -226,7 +232,11 @@ Runs a hybrid search that fuses vector similarity with full-text results through
 
 **indexName** (`string`): Name of the Mastra index to search
 
-**queryVector** (`number[]`): Query vector for similarity search
+**queryVector** (`number[]`): Query vector for the vector branch. Supply this or queryText, not both.
+
+**queryText** (`string`): Text for MongoDB to embed for the vector branch. autoEmbed indexes only. Independent of query, so each branch can search for something different.
+
+**model** (`string`): Embedding model for the vector branch, overriding the index's. Requires queryText.
 
 **query** (`string`): Full-text search query string
 
@@ -273,6 +283,8 @@ interface IndexStats {
 }
 ```
 
+On an `autoEmbed` index, `dimension` is read from the index definition and reports MongoDB's default of `1024` when the index doesn't pin one. `count` counts documents that carry the embedded text field, since the generated vectors aren't stored on your documents.
+
 ### `deleteIndex()`
 
 Deletes a vector index. Behavior depends on how the index was created:
@@ -367,6 +379,79 @@ try {
 }
 ```
 
+## Automated Embedding
+
+MongoDB can generate the embeddings for you. Create the index with `autoEmbed` and a Voyage AI model, write plain text through `documents`, and search with `queryText`. No embedding provider runs in your application, and no vectors travel through it.
+
+```typescript
+import { MongoDBVector } from '@mastra/mongodb'
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DB_NAME,
+})
+
+// No `dimension`: the embedding model determines it.
+await store.createIndex({
+  indexName: 'movies',
+  autoEmbed: { model: 'voyage-4' },
+  filterFields: ['year'],
+})
+
+// Automated Embedding indexes build slower than client-embedded ones.
+await store.waitForIndexReady({ indexName: 'movies', timeoutMs: 300000 })
+
+// No `vectors`: MongoDB embeds the text as documents are written.
+await store.upsert({
+  indexName: 'movies',
+  documents: [
+    'A lonely astronaut adrift near a strange ocean planet.',
+    'A heist crew robs a bank vault in Paris.',
+  ],
+  metadata: [{ year: 1972 }, { year: 2001 }],
+})
+
+// No `queryVector`: MongoDB embeds the query string with the same model.
+const results = await store.query({
+  indexName: 'movies',
+  queryText: 'space opera about isolation',
+  topK: 5,
+  filter: { year: { $gt: 1970 } },
+})
+```
+
+### `autoEmbed` options
+
+**model** (`string`): Voyage AI model to embed with, for example voyage-4. MongoDB rejects a name it does not support and lists the ones it does.
+
+**path** (`string`): Text field to embed. Defaults to the managed document field that upsert({ documents }) writes. Point it at a field of your own to index an existing collection in place. (Default: `document`)
+
+**similarity** (`'cosine' | 'dotProduct' | 'euclidean'`): Vector similarity function. Defaults to MongoDB's own default when omitted.
+
+**numDimensions** (`256 | 512 | 1024 | 2048`): Length of the generated embeddings. (Default: `1024`)
+
+**quantization** (`'float' | 'scalar' | 'binary' | 'binaryNoRescore'`): Storage format for the generated vectors. (Default: `scalar`)
+
+**indexingMethod** (`'hnsw' | 'flat'`): Index structure for the vector field. (Default: `hnsw`)
+
+**hnswOptions** (`{ maxEdges?: number; numEdgeCandidates?: number }`): Tuning for the HNSW graph. MongoDB's defaults suit most workloads.
+
+Any other field the `autoEmbed` index definition accepts is forwarded to MongoDB as given, so options added after this release work without a package update. Anything omitted keeps MongoDB's default.
+
+**Important notes:**
+
+- Automated Embedding is a **MongoDB Preview feature**. It requires an Atlas cluster with Automated Embedding available, or the `mongodb/mongodb-atlas-local:preview` image for local development. Self-managed deployments need `mongot` configured with a Voyage AI API key.
+- The Voyage AI API key must be provisioned through the Atlas UI. A key issued directly by Voyage AI is rejected by the default embedding endpoint.
+- **MongoDB stores the generated vectors outside your collection**, so documents carry text only. `includeVector: true` isn't supported on an `autoEmbed` index and throws.
+- Embeddings are generated asynchronously. A query can legitimately return no results for a short time after a write, even once the index reports ready.
+- An index declares either a vector field or an `autoEmbed` field, never both. Omit `autoEmbed` to keep supplying your own vectors. The client-side path is unchanged.
+- Passing `vectors` to an `autoEmbed` index is an error, since they would be written to a field no index reads.
+- When `document` is the embedded field it's no longer a declared filter field, so `documentFilter` uses the `$match` pre-filter automatically. Metadata filters declared through `filterFields` still push into `$vectorSearch`.
+- `updateVector()` rejects a vector update on an `autoEmbed` index. Upsert the document with new text instead, and MongoDB re-embeds it.
+- `queryVector` still works against an `autoEmbed` index, but the vector must come from a compatible model and match the index `quantization`. MongoDB rejects a mismatch.
+- Embedding generation is billed per token, for both documents and queries.
+
 ## Indexing an existing collection
 
 You can create a vector index on an existing operational collection instead of using a managed collection. This is useful when you want to add vector search capabilities to documents that already exist in your MongoDB database.