@mastra/lance 1.1.0 → 1.1.1-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @mastra/lance
 
+## 1.1.1-alpha.0
+
+### Patch Changes
+
+- Fixed `LanceVectorStore.query()` returning a raw LanceDB distance in the `score` field, which inverted ranking compared to every other Mastra vector store. ([#18104](https://github.com/mastra-ai/mastra/pull/18104))
+
+  LanceDB's `_distance` is a distance (lower = more similar), while Mastra's `score` is a similarity (higher = more similar). Returning the distance unchanged meant the closest match got the _lowest_ score, silently breaking `Memory` semantic recall, `rerank()` vector weighting, and any `minScore`/threshold filtering written against other stores (pg, Chroma, S3 Vectors, Pinecone, …).
+
+  `query()` now converts `_distance` into a similarity score consistent with the other stores and sets the search distance type to match the detected index metric, or an explicit query metric when no physical Lance index exists:
+  - cosine → `1 - distance` (cosine similarity)
+  - dot product → `1 - distance` (recovers the dot product, matching `@mastra/pg`)
+  - euclidean → `1 / (1 + sqrt(distance))` (Lance `l2` returns squared L2, so this maps to Mastra's L2 similarity semantics)
+
+  The metric defaults to the table's vector index metric when one exists, otherwise `cosine` (matching `createIndex`'s default). For small/unindexed tables where LanceDB has no physical index metadata to inspect, pass `metric` to `query()` when using a non-cosine metric. If a query metric conflicts with an existing Lance index metric, the index metric is used because Lance requires indexed searches to use the index's distance type:
+
+  ```ts
+  // Before: `exact` got score 0, `far` got score 2 — ranking inverted.
+  // After:  `exact` gets the highest score and ranks first.
+  const results = await store.query({
+    indexName: 'docs',
+    queryVector: [1, 0, 0],
+    topK: 2,
+    metric: 'cosine', // optional; resolved from the index by default
+  });
+  ```
+
+- Updated dependencies [[`6a1428a`](https://github.com/mastra-ai/mastra/commit/6a1428a23133fc070fc6c1caa08d28f3ba4fe5ff), [`7f51548`](https://github.com/mastra-ai/mastra/commit/7f515481213780be7047cef00640b9d35f3d545c)]:
+  - @mastra/core@1.46.0-alpha.2
+
 ## 1.1.0
 
 ### Minor Changes

package/dist/docs/SKILL.md

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

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.0",
+  "version": "1.1.1-alpha.0",
   "package": "@mastra/lance",
   "exports": {},
   "modules": {}

package/dist/index.cjs

@@ -2647,7 +2647,8 @@ var LanceVectorStore = class _LanceVectorStore extends vector.MastraVector {
     includeVector = false,
     topK = 10,
     columns = [],
-    includeAllColumns = false
+    includeAllColumns = false,
+    metric
   }) {
     const resolvedTableName = tableName ?? indexName;
     if (!queryVector) {
@@ -2685,7 +2686,11 @@ var LanceVectorStore = class _LanceVectorStore extends vector.MastraVector {
         return [];
       }
       const table = await this.lanceClient.openTable(resolvedTableName);
-      let query = table.search(queryVector);
+      const resolvedMetric = await this.resolveQueryMetric(table, {
+        columnName: tableName ? indexName : "vector",
+        explicitMetric: metric
+      });
+      let query = table.vectorSearch(queryVector).distanceType(this.mastraMetricToLance(resolvedMetric));
       if (filter && Object.keys(filter).length > 0) {
         const whereClause = this.filterTranslator(filter);
         this.logger.debug(`Where clause generated: ${whereClause}`);
@@ -2706,6 +2711,9 @@ var LanceVectorStore = class _LanceVectorStore extends vector.MastraVector {
         if (!selectColumns.includes("id")) {
           selectColumns.push("id");
         }
+        if (!selectColumns.includes("_distance")) {
+          selectColumns.push("_distance");
+        }
         query = query.select(selectColumns);
       }
       query = query.limit(topK);
@@ -2726,7 +2734,7 @@ var LanceVectorStore = class _LanceVectorStore extends vector.MastraVector {
           metadata,
           vector: includeVector && result.vector ? Array.isArray(result.vector) ? result.vector : Array.from(result.vector) : void 0,
           document: result.document,
-          score: result._distance
+          score: this.distanceToScore(result._distance, resolvedMetric)
         };
       });
     } catch (error$1) {
@@ -2741,6 +2749,85 @@ var LanceVectorStore = class _LanceVectorStore extends vector.MastraVector {
       );
     }
   }
+  /**
+   * Maps a Mastra distance metric to the LanceDB distance type.
+   */
+  mastraMetricToLance(metric) {
+    switch (metric) {
+      case "euclidean":
+        return "l2";
+      case "dotproduct":
+        return "dot";
+      case "cosine":
+      default:
+        return "cosine";
+    }
+  }
+  /**
+   * Determines the distance metric to use for a query.
+   *
+   * Precedence: the table's vector index metric wins when an index exists because
+   * LanceDB requires indexed searches to use the same distance type the index was
+   * trained with; otherwise an explicitly provided metric is used; otherwise it
+   * defaults to 'cosine'.
+   */
+  async resolveQueryMetric(table, {
+    columnName,
+    explicitMetric
+  }) {
+    try {
+      const indices = await table.listIndices();
+      const matchingIndices = indices.filter((index) => index.columns?.includes(columnName));
+      for (const index of matchingIndices.length > 0 ? matchingIndices : indices) {
+        const stats = await table.indexStats(index.name);
+        const resolved = this.lanceMetricToMastra(stats?.distanceType);
+        if (resolved) {
+          if (explicitMetric && explicitMetric !== resolved) {
+            this.logger.warn(
+              `Ignoring query metric "${explicitMetric}" because Lance index "${index.name}" uses "${resolved}".`
+            );
+          }
+          return resolved;
+        }
+      }
+    } catch (error) {
+      this.logger.debug("Failed to resolve metric from Lance index stats.", error);
+    }
+    return explicitMetric ?? "cosine";
+  }
+  lanceMetricToMastra(metric) {
+    switch (metric) {
+      case "l2":
+        return "euclidean";
+      case "dot":
+        return "dotproduct";
+      case "cosine":
+        return "cosine";
+      default:
+        return void 0;
+    }
+  }
+  /**
+   * Converts a LanceDB `_distance` (smaller = more similar) into a Mastra similarity
+   * `score` (larger = more similar), consistent with every other Mastra vector store.
+   *
+   * - cosine: LanceDB returns cosine distance (`1 - cosine_similarity`), so `1 - distance`
+   *   recovers the cosine similarity.
+   * - dotproduct: LanceDB's dot distance is `1 - dot_product`, so `1 - distance` recovers
+   *   the dot product (matching `@mastra/pg`).
+   * - euclidean: LanceDB returns squared L2 distance for `l2`, so use its square root
+   *   before mapping into (0, 1] (matching `@mastra/pg`).
+   */
+  distanceToScore(distance, metric) {
+    switch (metric) {
+      case "euclidean":
+        return 1 / (1 + Math.sqrt(distance));
+      case "dotproduct":
+      case "cosine":
+      default:
+        return 1 - distance;
+    }
+  }
   filterTranslator(filter) {
     const processFilterKeys = (filterObj) => {
       const result = {};
@@ -3033,14 +3120,7 @@ var LanceVectorStore = class _LanceVectorStore extends vector.MastraVector {
       } else {
         table = await this.lanceClient.openTable(resolvedTableName);
       }
-      let metricType;
-      if (metric === "euclidean") {
-        metricType = "l2";
-      } else if (metric === "dotproduct") {
-        metricType = "dot";
-      } else if (metric === "cosine") {
-        metricType = "cosine";
-      }
+      const metricType = this.mastraMetricToLance(metric);
       const rowCount = await table.countRows();
       if (rowCount < 256) {
         this.logger.warn(
@@ -3145,7 +3225,7 @@ var LanceVectorStore = class _LanceVectorStore extends vector.MastraVector {
           const dimension = vectorField?.type?.["listSize"] || 0;
           return {
             dimension,
-            metric: stats.distanceType,
+            metric: this.lanceMetricToMastra(stats.distanceType),
             count: stats.numIndexedRows
           };
         }