@mastra/mongodb 1.13.0 → 1.14.0-alpha.0

package/dist/vector/index.d.ts

@@ -15,6 +15,19 @@ export interface MongoDBQueryVectorParams extends QueryVectorParams<MongoDBVecto
      */
     numCandidates?: number;
 }
+export interface MongoDBCreateIndexParams extends CreateIndexParams {
+    /**
+     * Metadata field names to declare as filter fields in the Atlas vectorSearch
+     * index (registered as `metadata.<field>`). Queries whose metadata filter
+     * only touches declared fields — using operators `$vectorSearch.filter`
+     * supports — are passed directly to `$vectorSearch` instead of pre-filtering
+     * candidate `_id`s, avoiding the 16 MB BSON limit on large result sets.
+     * Filters that reference an undeclared field, or use an unsupported
+     * operator, automatically fall back to the pre-filter.
+     * @see https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-type/
+     */
+    filterFields?: string[];
+}
 export interface MongoDBVectorConfig {
     /** Unique identifier for this vector store instance */
     id: string;
@@ -43,6 +56,20 @@ export declare class MongoDBVector extends MastraVector<MongoDBVectorFilter> {
     private readonly embeddingFieldName;
     private readonly metadataFieldName;
     private readonly documentFieldName;
+    /**
+     * Per-index cache of the filter paths declared in the Atlas vectorSearch index
+     * (e.g. `document`, `metadata.category`). Populated when an index is created in
+     * this process and lazily hydrated from the live index definition otherwise.
+     * `_id` is excluded because it is materialised separately by the fallback path.
+     */
+    private declaredFilterPaths;
+    /**
+     * MongoDB query operators supported inside `$vectorSearch.filter`. Intentionally
+     * conservative: filters using any operator outside this set fall back to the
+     * `$match` pre-filter, which supports the full query language. Widening this set
+     * is safe only for operators Atlas Vector Search actually accepts in `filter`.
+     */
+    private static readonly PUSHDOWN_OPERATORS;
     private mongoMetricMap;
     constructor({ id, uri, dbName, options, embeddingFieldPath }: MongoDBVectorConfig);
     connect(): Promise<void>;
@@ -58,7 +85,13 @@ export declare class MongoDBVector extends MastraVector<MongoDBVectorFilter> {
      * queryable. Skipping that step on a real Atlas cluster may cause
      * "index not found" or "index not ready" errors on subsequent operations.
      */
-    createIndex({ indexName, dimension, metric }: CreateIndexParams): Promise<void>;
+    createIndex({ indexName, dimension, metric, filterFields, }: MongoDBCreateIndexParams): Promise<void>;
+    /**
+     * Creates an Atlas Search index, treating IndexAlreadyExists as a no-op so
+     * `createIndex` stays idempotent per index. Returns true when the index was
+     * actually created by this call.
+     */
+    private createSearchIndexIgnoringExisting;
     /**
      * Waits for the index to be ready.
      *
@@ -151,6 +184,27 @@ export declare class MongoDBVector extends MastraVector<MongoDBVectorFilter> {
      */
     private getCollection;
     private validateVectorDimensions;
+    /**
+     * Maps user-facing `filterFields` (bare metadata field names) to the fully
+     * qualified filter paths stored in the index, e.g. `category` → `metadata.category`.
+     * Blank entries are dropped and duplicates collapsed. A name already carrying the
+     * `metadata.` prefix is left untouched so callers can pass either form.
+     */
+    private buildDeclaredMetadataPaths;
+    /**
+     * Returns the set of filter paths declared in the vectorSearch index (e.g.
+     * `document`, `metadata.category`), excluding `_id`. Reads the live index
+     * definition once per index and caches the result. Used to decide whether a
+     * metadata filter can be pushed down into `$vectorSearch.filter`.
+     */
+    private getDeclaredFilterPaths;
+    /**
+     * True when `filter` can be passed directly to `$vectorSearch.filter`: every
+     * field path it references is a declared filter field and every operator is in
+     * {@link MongoDBVector.PUSHDOWN_OPERATORS}. Conservative by design — anything it
+     * can't prove safe returns false so the caller uses the `$match` pre-filter.
+     */
+    private canPushDownFilter;
     private transformFilter;
     /**
      * Transform metadata field filters to use MongoDB dot notation.

package/dist/vector/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vector/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vector/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mongodb",
-  "version": "1.13.0",
+  "version": "1.14.0-alpha.0",
   "description": "MongoDB provider for Mastra - includes vector store capabilities",
   "type": "module",
   "main": "dist/index.js",
@@ -27,15 +27,15 @@
     "@types/node": "22.20.1",
     "@vitest/coverage-v8": "4.1.10",
     "@vitest/ui": "4.1.10",
-    "eslint": "^10.4.1",
+    "eslint": "^10.7.0",
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
     "@internal/lint": "0.0.114",
+    "@internal/storage-test-utils": "0.0.110",
     "@internal/types-builder": "0.0.89",
-    "@mastra/core": "1.51.0",
-    "@internal/storage-test-utils": "0.0.110"
+    "@mastra/core": "1.52.0-alpha.8"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.51.0-0 <2.0.0-0"