@mastra/mongodb 1.13.0 → 1.14.0-alpha.0

package/dist/index.js

@@ -13,7 +13,7 @@ import { skillSnapshotFieldValuesEqual } from '@mastra/core/storage/domains/skil
 
 // package.json
 var package_default = {
-  version: "1.13.0"};
+  version: "1.14.0-alpha.0"};
 var MongoDBFilterTranslator = class extends BaseFilterTranslator {
   getSupportedOperators() {
     return {
@@ -103,13 +103,38 @@ var MongoDBFilterTranslator = class extends BaseFilterTranslator {
 };
 
 // src/vector/index.ts
-var MongoDBVector = class extends MastraVector {
+var MongoDBVector = class _MongoDBVector extends MastraVector {
   client;
   db;
   collections;
   embeddingFieldName;
   metadataFieldName = "metadata";
   documentFieldName = "document";
+  /**
+   * 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.
+   */
+  declaredFilterPaths = /* @__PURE__ */ new Map();
+  /**
+   * 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`.
+   */
+  static PUSHDOWN_OPERATORS = /* @__PURE__ */ new Set([
+    "$and",
+    "$or",
+    "$eq",
+    "$ne",
+    "$gt",
+    "$gte",
+    "$lt",
+    "$lte",
+    "$in",
+    "$nin"
+  ]);
   mongoMetricMap = {
     cosine: "cosine",
     euclidean: "euclidean",
@@ -172,7 +197,12 @@ var MongoDBVector = class extends MastraVector {
    * queryable. Skipping that step on a real Atlas cluster may cause
    * "index not found" or "index not ready" errors on subsequent operations.
    */
-  async createIndex({ indexName, dimension, metric = "cosine" }) {
+  async createIndex({
+    indexName,
+    dimension,
+    metric = "cosine",
+    filterFields
+  }) {
     let mongoMetric;
     try {
       if (!Number.isInteger(dimension) || dimension <= 0) {
@@ -207,29 +237,33 @@ var MongoDBVector = class extends MastraVector {
       const indexNameInternal = `${indexName}_vector_index`;
       const embeddingField = this.embeddingFieldName;
       const numDimensions = dimension;
-      await collection.createSearchIndex({
-        definition: {
-          fields: [
-            {
-              type: "vector",
-              path: embeddingField,
-              numDimensions,
-              similarity: mongoMetric
-            },
-            {
-              type: "filter",
-              path: "_id"
-            },
-            {
-              type: "filter",
-              path: "document"
-            }
-          ]
+      const declaredMetadataPaths = this.buildDeclaredMetadataPaths(filterFields);
+      const fields = [
+        {
+          type: "vector",
+          path: embeddingField,
+          numDimensions,
+          similarity: mongoMetric
+        },
+        {
+          type: "filter",
+          path: "_id"
         },
+        {
+          type: "filter",
+          path: this.documentFieldName
+        },
+        ...declaredMetadataPaths.map((path) => ({ type: "filter", path }))
+      ];
+      const vectorIndexCreated = await this.createSearchIndexIgnoringExisting(collection, {
+        definition: { fields },
         name: indexNameInternal,
         type: "vectorSearch"
       });
-      await collection.createSearchIndex({
+      if (vectorIndexCreated) {
+        this.declaredFilterPaths.set(indexName, /* @__PURE__ */ new Set([this.documentFieldName, ...declaredMetadataPaths]));
+      }
+      await this.createSearchIndexIgnoringExisting(collection, {
         definition: {
           mappings: {
             dynamic: true
@@ -239,16 +273,30 @@ var MongoDBVector = class extends MastraVector {
         type: "search"
       });
     } catch (error) {
-      if (error.codeName !== "IndexAlreadyExists") {
-        throw new MastraError(
-          {
-            id: createVectorErrorId("MONGODB", "CREATE_INDEX", "FAILED"),
-            domain: ErrorDomain.STORAGE,
-            category: ErrorCategory.THIRD_PARTY
-          },
-          error
-        );
+      throw new MastraError(
+        {
+          id: createVectorErrorId("MONGODB", "CREATE_INDEX", "FAILED"),
+          domain: ErrorDomain.STORAGE,
+          category: ErrorCategory.THIRD_PARTY
+        },
+        error
+      );
+    }
+  }
+  /**
+   * 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.
+   */
+  async createSearchIndexIgnoringExisting(collection, description) {
+    try {
+      await collection.createSearchIndex(description);
+      return true;
+    } catch (error) {
+      if (error?.codeName === "IndexAlreadyExists") {
+        return false;
       }
+      throw error;
     }
   }
   /**
@@ -390,9 +438,19 @@ var MongoDBVector = class extends MastraVector {
         limit: Math.min(1e4, topK)
       };
       if (hasMetadataFilter) {
-        const candidateIds = await collection.aggregate([{ $match: metadataFilter }, { $project: { _id: 1 } }]).map((doc) => doc._id).toArray();
-        if (candidateIds.length === 0) return [];
-        vectorSearch.filter = documentFilter ? { $and: [{ _id: { $in: candidateIds } }, { [this.documentFieldName]: documentFilter }] } : { _id: { $in: candidateIds } };
+        let declaredPaths;
+        try {
+          declaredPaths = await this.getDeclaredFilterPaths(indexName);
+        } catch {
+          declaredPaths = /* @__PURE__ */ new Set();
+        }
+        if (this.canPushDownFilter(metadataFilter, declaredPaths)) {
+          vectorSearch.filter = documentFilter ? { $and: [metadataFilter, { [this.documentFieldName]: documentFilter }] } : metadataFilter;
+        } else {
+          const candidateIds = await collection.aggregate([{ $match: metadataFilter }, { $project: { _id: 1 } }]).map((doc) => doc._id).toArray();
+          if (candidateIds.length === 0) return [];
+          vectorSearch.filter = documentFilter ? { $and: [{ _id: { $in: candidateIds } }, { [this.documentFieldName]: documentFilter }] } : { _id: { $in: candidateIds } };
+        }
       } else if (documentFilter) {
         vectorSearch.filter = { [this.documentFieldName]: documentFilter };
       }
@@ -509,6 +567,7 @@ var MongoDBVector = class extends MastraVector {
       if (collection) {
         await collection.drop();
         this.collections.delete(indexName);
+        this.declaredFilterPaths.delete(indexName);
       } else {
         throw new Error(`Index (Collection) "${indexName}" does not exist`);
       }
@@ -775,6 +834,66 @@ var MongoDBVector = class extends MastraVector {
       }
     }
   }
+  /**
+   * 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.
+   */
+  buildDeclaredMetadataPaths(filterFields) {
+    if (!filterFields?.length) return [];
+    const paths = /* @__PURE__ */ new Set();
+    for (const field of filterFields) {
+      const trimmed = field?.trim();
+      if (!trimmed) continue;
+      paths.add(trimmed.startsWith(`${this.metadataFieldName}.`) ? trimmed : `${this.metadataFieldName}.${trimmed}`);
+    }
+    return [...paths];
+  }
+  /**
+   * 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`.
+   */
+  async getDeclaredFilterPaths(indexName) {
+    const cached = this.declaredFilterPaths.get(indexName);
+    if (cached) return cached;
+    const collection = await this.getCollection(indexName, true);
+    const indexNameInternal = `${indexName}_vector_index`;
+    const indexInfo = await collection.listSearchIndexes().toArray();
+    const indexData = indexInfo.find((idx) => idx.name === indexNameInternal);
+    const paths = /* @__PURE__ */ new Set();
+    if (indexData?.status !== "READY") {
+      return paths;
+    }
+    for (const field of indexData.latestDefinition?.fields ?? []) {
+      if (field?.type === "filter" && typeof field.path === "string" && field.path !== "_id") {
+        paths.add(field.path);
+      }
+    }
+    this.declaredFilterPaths.set(indexName, paths);
+    return paths;
+  }
+  /**
+   * 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.
+   */
+  canPushDownFilter(filter, declaredPaths) {
+    if (filter === null || typeof filter !== "object") return true;
+    if (Array.isArray(filter)) return filter.every((item) => this.canPushDownFilter(item, declaredPaths));
+    for (const [key, value] of Object.entries(filter)) {
+      if (key.startsWith("$")) {
+        if (!_MongoDBVector.PUSHDOWN_OPERATORS.has(key)) return false;
+      } else if (!declaredPaths.has(key)) {
+        return false;
+      }
+      if (!this.canPushDownFilter(value, declaredPaths)) return false;
+    }
+    return true;
+  }
   transformFilter(filter) {
     const translator = new MongoDBFilterTranslator();
     if (!filter) return {};