fix(storage): correct QueryVectorsResponse to use vectors instead of matches (#1922)

Author: mandarini

packages/core/storage-js/src/lib/vectors/types.ts

@@ -258,10 +258,12 @@ export interface QueryVectorsOptions {
 
 /**
  * Response from vector similarity query
- * @property matches - Array of similar vectors ordered by distance
+ * @property vectors - Array of similar vectors ordered by distance
+ * @property distanceMetric - The distance metric used for the similarity search
  */
 export interface QueryVectorsResponse {
-  matches: VectorMatch[]
+  vectors: VectorMatch[]
+  distanceMetric?: DistanceMetric
 }
 
 /**

packages/core/storage-js/test/e2e-workflow.spec.ts

@@ -98,11 +98,11 @@ describe('End-to-End Workflow Tests', () => {
       })
 
       const queryData = assertSuccessResponse(queryResponse)
-      expect(queryData.matches.length).toBeGreaterThan(0)
-      expect(queryData.matches.length).toBeLessThanOrEqual(2)
+      expect(queryData.vectors.length).toBeGreaterThan(0)
+      expect(queryData.vectors.length).toBeLessThanOrEqual(2)
 
       // All matches should have published: true
-      for (const match of queryData.matches) {
+      for (const match of queryData.vectors) {
         expect(match.metadata?.published).toBe(true)
       }
 
@@ -240,7 +240,7 @@ describe('End-to-End Workflow Tests', () => {
           returnMetadata: true,
         })
         const data = assertSuccessResponse(response)
-        expect(data.matches.length).toBeGreaterThan(0)
+        expect(data.vectors.length).toBeGreaterThan(0)
       }
 
       // Cleanup: Delete all indexes
@@ -329,8 +329,8 @@ describe('End-to-End Workflow Tests', () => {
       })
 
       const tech1Data = assertSuccessResponse(tech1Response)
-      expect(tech1Data.matches.length).toBeGreaterThan(0)
-      for (const match of tech1Data.matches) {
+      expect(tech1Data.vectors.length).toBeGreaterThan(0)
+      for (const match of tech1Data.vectors) {
         expect(match.metadata?.type).toBe('article')
         expect(match.metadata?.category).toBe('technology')
       }
@@ -344,8 +344,8 @@ describe('End-to-End Workflow Tests', () => {
       })
 
       const year2024Data = assertSuccessResponse(year2024Response)
-      expect(year2024Data.matches.length).toBeGreaterThan(0)
-      for (const match of year2024Data.matches) {
+      expect(year2024Data.vectors.length).toBeGreaterThan(0)
+      for (const match of year2024Data.vectors) {
         expect(match.metadata?.year).toBe(2024)
       }
 
@@ -358,8 +358,8 @@ describe('End-to-End Workflow Tests', () => {
       })
 
       const papersData = assertSuccessResponse(papersResponse)
-      expect(papersData.matches.length).toBeGreaterThan(0)
-      for (const match of papersData.matches) {
+      expect(papersData.vectors.length).toBeGreaterThan(0)
+      for (const match of papersData.vectors) {
         expect(match.metadata?.type).toBe('paper')
       }
 
@@ -419,8 +419,8 @@ describe('End-to-End Workflow Tests', () => {
       })
 
       const queryData = assertSuccessResponse(queryResponse)
-      expect(queryData.matches.length).toBeGreaterThan(0)
-      expect(queryData.matches.length).toBeLessThanOrEqual(10)
+      expect(queryData.vectors.length).toBeGreaterThan(0)
+      expect(queryData.vectors.length).toBeLessThanOrEqual(10)
 
       // Delete in batches
       const keysToDelete = Array.from({ length: 100 }, (_, i) => `vector-${i}`)

packages/core/storage-js/test/mock-server.ts

@@ -662,7 +662,7 @@ function handleQueryVectors(body: any): MockResponse {
   }
 
   // Calculate cosine similarity (simplified mock)
-  const matches = allVectors
+  const vectors = allVectors
     .map((vector, index) => {
       const result: any = { key: vector.key }
       if (returnDistance) {
@@ -676,7 +676,7 @@ function handleQueryVectors(body: any): MockResponse {
 
   return {
     status: 200,
-    data: { matches },
+    data: { vectors, distanceMetric: 'cosine' },
   }
 }
 

packages/core/storage-js/test/vector-data-api.spec.ts

@@ -424,10 +424,10 @@ describe('VectorDataApi Integration Tests', () => {
       })
 
       const data = assertSuccessResponse(response)
-      expect(data.matches).toBeDefined()
-      expect(Array.isArray(data.matches)).toBe(true)
-      expect(data.matches.length).toBeGreaterThan(0)
-      expect(data.matches.length).toBeLessThanOrEqual(3)
+      expect(data.vectors).toBeDefined()
+      expect(Array.isArray(data.vectors)).toBe(true)
+      expect(data.vectors.length).toBeGreaterThan(0)
+      expect(data.vectors.length).toBeLessThanOrEqual(3)
     })
 
     it('should return vectors with distance scores', async () => {
@@ -441,8 +441,8 @@ describe('VectorDataApi Integration Tests', () => {
       })
 
       const data = assertSuccessResponse(response)
-      expect(data.matches[0].distance).toBeDefined()
-      expect(typeof data.matches[0].distance).toBe('number')
+      expect(data.vectors[0].distance).toBeDefined()
+      expect(typeof data.vectors[0].distance).toBe('number')
     })
 
     it('should filter by metadata', async () => {
@@ -456,10 +456,10 @@ describe('VectorDataApi Integration Tests', () => {
       })
 
       const data = assertSuccessResponse(response)
-      expect(data.matches.length).toBeGreaterThan(0)
+      expect(data.vectors.length).toBeGreaterThan(0)
 
       // All results should match filter
-      for (const match of data.matches) {
+      for (const match of data.vectors) {
         expect(match.metadata?.category).toBe('tech')
       }
     })
@@ -476,7 +476,7 @@ describe('VectorDataApi Integration Tests', () => {
 
       const data = assertSuccessResponse(response)
 
-      for (const match of data.matches) {
+      for (const match of data.vectors) {
         expect(match.metadata?.category).toBe('tech')
         expect(match.metadata?.published).toBe(true)
       }
@@ -491,7 +491,7 @@ describe('VectorDataApi Integration Tests', () => {
       })
 
       const data = assertSuccessResponse(response)
-      expect(data.matches.length).toBeLessThanOrEqual(2)
+      expect(data.vectors.length).toBeLessThanOrEqual(2)
     })
 
     it('should return empty matches when filter matches nothing', async () => {
@@ -504,7 +504,7 @@ describe('VectorDataApi Integration Tests', () => {
       })
 
       const data = assertSuccessResponse(response)
-      expect(data.matches).toEqual([])
+      expect(data.vectors).toEqual([])
     })
 
     it('should query without metadata in results', async () => {
@@ -518,8 +518,8 @@ describe('VectorDataApi Integration Tests', () => {
       })
 
       const data = assertSuccessResponse(response)
-      expect(data.matches[0].key).toBeDefined()
-      expect(data.matches[0].metadata).toBeUndefined()
+      expect(data.vectors[0].key).toBeDefined()
+      expect(data.vectors[0].metadata).toBeUndefined()
     })
   })