@mastra/chroma 0.0.0-storage-20250225005900 → 0.0.0-trigger-playground-ui-package-20250506151043

package/src/vector/index.test.ts

@@ -1,5 +1,5 @@
-import { QueryResult, IndexStats } from '@mastra/core/vector';
-import { describe, expect, beforeEach, afterEach, it, beforeAll, afterAll } from 'vitest';
+import type { QueryResult, IndexStats } from '@mastra/core/vector';
+import { describe, expect, beforeEach, afterEach, it, beforeAll, afterAll, vi } from 'vitest';
 
 import { ChromaVector } from './';
 
@@ -10,23 +10,24 @@ describe('ChromaVector Integration Tests', () => {
 
   const testIndexName = 'test-index';
   const testIndexName2 = 'test-index-2';
+  const testIndexName3 = 'test-index-3';
   const dimension = 3;
 
   beforeEach(async () => {
     // Clean up any existing test index
     try {
       await vectorDB.deleteIndex(testIndexName);
-    } catch (error) {
+    } catch {
       // Ignore errors if index doesn't exist
     }
-    await vectorDB.createIndex(testIndexName, dimension);
+    await vectorDB.createIndex({ indexName: testIndexName, dimension });
   }, 5000);
 
   afterEach(async () => {
     // Cleanup after tests
     try {
       await vectorDB.deleteIndex(testIndexName);
-    } catch (error) {
+    } catch {
       // Ignore cleanup errors
     }
   }, 5000);
@@ -55,7 +56,7 @@ describe('ChromaVector Integration Tests', () => {
 
       for (const metric of metricsToTest) {
         const testIndex = `test-index-${metric}`;
-        await vectorDB.createIndex(testIndex, dimension, metric);
+        await vectorDB.createIndex({ indexName: testIndex, dimension, metric });
 
         const stats = await vectorDB.describeIndex(testIndex);
         expect(stats.metric).toBe(metric);
@@ -75,7 +76,7 @@ describe('ChromaVector Integration Tests', () => {
     const testIds = ['vec1', 'vec2', 'vec3'];
 
     it('should upsert vectors with generated ids', async () => {
-      const ids = await vectorDB.upsert(testIndexName, testVectors);
+      const ids = await vectorDB.upsert({ indexName: testIndexName, vectors: testVectors });
       expect(ids).toHaveLength(testVectors.length);
       ids.forEach(id => expect(typeof id).toBe('string'));
 
@@ -84,14 +85,14 @@ describe('ChromaVector Integration Tests', () => {
     });
 
     it('should upsert vectors with provided ids and metadata', async () => {
-      await vectorDB.upsert(testIndexName, testVectors, testMetadata, testIds);
+      await vectorDB.upsert({ indexName: testIndexName, vectors: testVectors, metadata: testMetadata, ids: testIds });
 
       const stats = await vectorDB.describeIndex(testIndexName);
       expect(stats.count).toBe(testVectors.length);
 
       // Query each vector to verify metadata
       for (let i = 0; i < testVectors.length; i++) {
-        const results = await vectorDB.query(testIndexName, testVectors?.[i]!, 1);
+        const results = await vectorDB.query({ indexName: testIndexName, queryVector: testVectors?.[i]!, topK: 1 });
         expect(results?.[0]?.id).toBe(testIds[i]);
         expect(results?.[0]?.metadata).toEqual(testMetadata[i]);
       }
@@ -99,18 +100,121 @@ describe('ChromaVector Integration Tests', () => {
 
     it('should update existing vectors', async () => {
       // Initial upsert
-      await vectorDB.upsert(testIndexName, testVectors, testMetadata, testIds);
+      await vectorDB.upsert({ indexName: testIndexName, vectors: testVectors, metadata: testMetadata, ids: testIds });
 
       // Update first vector
       const updatedVector = [[0.5, 0.5, 0.0]];
       const updatedMetadata = [{ label: 'updated-x-axis' }];
-      await vectorDB.upsert(testIndexName, updatedVector, updatedMetadata, [testIds?.[0]!]);
+      await vectorDB.upsert({
+        indexName: testIndexName,
+        vectors: updatedVector,
+        metadata: updatedMetadata,
+        ids: [testIds?.[0]!],
+      });
 
       // Verify update
-      const results = await vectorDB.query(testIndexName, updatedVector?.[0]!, 1);
+      const results = await vectorDB.query({ indexName: testIndexName, queryVector: updatedVector?.[0]!, topK: 1 });
       expect(results?.[0]?.id).toBe(testIds[0]);
       expect(results?.[0]?.metadata).toEqual(updatedMetadata[0]);
     });
+
+    it('should update the vector by id', async () => {
+      const ids = await vectorDB.upsert({ indexName: testIndexName, vectors: testVectors });
+      expect(ids).toHaveLength(3);
+
+      const idToBeUpdated = ids[0];
+      const newVector = [1, 2, 3];
+      const newMetaData = {
+        test: 'updates',
+      };
+
+      const update = {
+        vector: newVector,
+        metadata: newMetaData,
+      };
+
+      await vectorDB.updateIndexById(testIndexName, idToBeUpdated, update);
+
+      const results: QueryResult[] = await vectorDB.query({
+        indexName: testIndexName,
+        queryVector: newVector,
+        topK: 2,
+        includeVector: true,
+      });
+      expect(results[0]?.id).toBe(idToBeUpdated);
+      expect(results[0]?.vector).toEqual(newVector);
+      expect(results[0]?.metadata).toEqual(newMetaData);
+    });
+
+    it('should only update the metadata by id', async () => {
+      const ids = await vectorDB.upsert({ indexName: testIndexName, vectors: testVectors });
+      expect(ids).toHaveLength(3);
+
+      const idToBeUpdated = ids[0];
+      const newMetaData = {
+        test: 'updates',
+      };
+
+      const update = {
+        metadata: newMetaData,
+      };
+
+      await vectorDB.updateIndexById(testIndexName, idToBeUpdated, update);
+
+      const results: QueryResult[] = await vectorDB.query({
+        indexName: testIndexName,
+        queryVector: testVectors[0],
+        topK: 2,
+        includeVector: true,
+      });
+      expect(results[0]?.id).toBe(idToBeUpdated);
+      expect(results[0]?.vector).toEqual(testVectors[0]);
+      expect(results[0]?.metadata).toEqual(newMetaData);
+    });
+
+    it('should only update vector embeddings by id', async () => {
+      const ids = await vectorDB.upsert({ indexName: testIndexName, vectors: testVectors });
+      expect(ids).toHaveLength(3);
+
+      const idToBeUpdated = ids[0];
+      const newVector = [1, 2, 3];
+
+      const update = {
+        vector: newVector,
+      };
+
+      await vectorDB.updateIndexById(testIndexName, idToBeUpdated, update);
+
+      const results: QueryResult[] = await vectorDB.query({
+        indexName: testIndexName,
+        queryVector: newVector,
+        topK: 2,
+        includeVector: true,
+      });
+      expect(results[0]?.id).toBe(idToBeUpdated);
+      expect(results[0]?.vector).toEqual(newVector);
+    });
+
+    it('should throw exception when no updates are given', async () => {
+      await expect(vectorDB.updateIndexById(testIndexName, 'id', {})).rejects.toThrow('No updates provided');
+    });
+
+    it('should delete the vector by id', async () => {
+      const ids = await vectorDB.upsert({ indexName: testIndexName, vectors: testVectors });
+      expect(ids).toHaveLength(3);
+      const idToBeDeleted = ids[0];
+
+      await vectorDB.deleteIndexById(testIndexName, idToBeDeleted);
+
+      const results: QueryResult[] = await vectorDB.query({
+        indexName: testIndexName,
+        queryVector: [1.0, 0.0, 0.0],
+        topK: 2,
+      });
+
+      expect(results).toHaveLength(2);
+      expect(results.map(res => res.id)).not.toContain(idToBeDeleted);
+    });
   });
 
   describe('Query Operations', () => {
@@ -123,7 +227,7 @@ describe('ChromaVector Integration Tests', () => {
     const testIds = ['vec1', 'vec2', 'vec3'];
 
     beforeEach(async () => {
-      await vectorDB.upsert(testIndexName, testVectors, testMetadata, testIds);
+      await vectorDB.upsert({ indexName: testIndexName, vectors: testVectors, metadata: testMetadata, ids: testIds });
     });
 
     describe('Basic Queries', () => {
@@ -131,7 +235,7 @@ describe('ChromaVector Integration Tests', () => {
         const queryVector = [1.0, 0.1, 0.1];
         const topK = 2;
 
-        const results: QueryResult[] = await vectorDB.query(testIndexName, queryVector, topK);
+        const results: QueryResult[] = await vectorDB.query({ indexName: testIndexName, queryVector, topK });
 
         expect(results).toHaveLength(topK);
         expect(results?.[0]?.id).toBe(testIds[0]); // Should match x-axis vector most closely
@@ -143,7 +247,7 @@ describe('ChromaVector Integration Tests', () => {
         const queryVector = [1.0, 1.0, 1.0];
         const filter = { label: 'x-axis' };
 
-        const results = await vectorDB.query(testIndexName, queryVector, 3, filter);
+        const results = await vectorDB.query({ indexName: testIndexName, queryVector, topK: 3, filter });
 
         expect(results).toHaveLength(1);
         expect(results?.[0]?.metadata?.label).toBe('x-axis');
@@ -155,7 +259,12 @@ describe('ChromaVector Integration Tests', () => {
         const queryVector = [1.0, 0.1, 0.1];
         const topK = 1;
 
-        const results = await vectorDB.query(testIndexName, queryVector, topK, undefined, true);
+        const results = await vectorDB.query({
+          indexName: testIndexName,
+          queryVector,
+          topK,
+          includeVector: true,
+        });
 
         expect(results).toHaveLength(topK);
         expect(results?.[0]?.vector).toEqual(testVectors[0]);
@@ -165,73 +274,95 @@ describe('ChromaVector Integration Tests', () => {
 
   describe('Error Handling', () => {
     it('should handle non-existent index queries', async () => {
-      await expect(vectorDB.query('non-existent-index-yu', [1, 2, 3])).rejects.toThrow();
+      await expect(vectorDB.query({ indexName: 'non-existent-index-yu', queryVector: [1, 2, 3] })).rejects.toThrow();
     });
 
     it('should handle invalid dimension vectors', async () => {
       const invalidVector = [1, 2, 3, 4]; // 4D vector for 3D index
-      await expect(vectorDB.upsert(testIndexName, [invalidVector])).rejects.toThrow();
+      await expect(vectorDB.upsert({ indexName: testIndexName, vectors: [invalidVector] })).rejects.toThrow();
     });
 
     it('should handle mismatched metadata and vectors length', async () => {
       const vectors = [[1, 2, 3]];
       const metadata = [{}, {}]; // More metadata than vectors
-      await expect(vectorDB.upsert(testIndexName, vectors, metadata)).rejects.toThrow();
+      await expect(vectorDB.upsert({ indexName: testIndexName, vectors, metadata })).rejects.toThrow();
     });
   });
 
   describe('Filter Validation in Queries', () => {
     it('rejects queries with null values', async () => {
       await expect(
-        vectorDB.query(testIndexName, [1, 0, 0], 10, {
-          field: null,
+        vectorDB.query({
+          indexName: testIndexName,
+          queryVector: [1, 0, 0],
+          filter: {
+            field: null,
+          },
         }),
       ).rejects.toThrow();
 
       await expect(
-        vectorDB.query(testIndexName, [1, 0, 0], 10, {
-          other: { $eq: null },
+        vectorDB.query({
+          indexName: testIndexName,
+          queryVector: [1, 0, 0],
+          filter: {
+            other: { $eq: null },
+          },
         }),
       ).rejects.toThrow();
     });
 
     it('validates array operator values', async () => {
       await expect(
-        vectorDB.query(testIndexName, [1, 0, 0], 10, {
-          tags: { $in: null },
+        vectorDB.query({
+          indexName: testIndexName,
+          queryVector: [1, 0, 0],
+          filter: {
+            tags: { $in: null },
+          },
         }),
       ).rejects.toThrow();
     });
 
     it('validates numeric values for comparison operators', async () => {
       await expect(
-        vectorDB.query(testIndexName, [1, 0, 0], 10, {
-          price: { $gt: 'not-a-number' },
+        vectorDB.query({
+          indexName: testIndexName,
+          queryVector: [1, 0, 0],
+          filter: {
+            price: { $gt: 'not-a-number' },
+          },
         }),
       ).rejects.toThrow();
     });
 
     it('validates value types', async () => {
       await expect(
-        vectorDB.query(testIndexName, [1, 0, 0], 10, {
-          date: { $gt: 'not-a-date' },
+        vectorDB.query({
+          indexName: testIndexName,
+          queryVector: [1, 0, 0],
+          filter: { date: { $gt: 'not-a-date' } },
         }),
       ).rejects.toThrow();
 
       await expect(
-        vectorDB.query(testIndexName, [1, 0, 0], 10, {
-          number: { $lt: 'not-a-number' },
+        vectorDB.query({
+          indexName: testIndexName,
+          queryVector: [1, 0, 0],
+          filter: { number: { $lt: 'not-a-number' } },
         }),
       ).rejects.toThrow();
     });
 
     it('validates array operators', async () => {
-      const invalidValues = [123, 'string', true, { key: 'value' }, null, undefined];
+      const invalidValues = [123, 'string', true, { key: 'value' }, null];
       for (const op of ['$in', '$nin']) {
         for (const val of invalidValues) {
           await expect(
-            vectorDB.query(testIndexName, [1, 0, 0], 10, {
-              field: { [op]: val },
+            vectorDB.query({
+              indexName: testIndexName,
+              queryVector: [1, 0, 0],
+              filter: { field: { [op]: val } },
             }),
           ).rejects.toThrow();
         }
@@ -244,8 +375,10 @@ describe('ChromaVector Integration Tests', () => {
       for (const op of ['$in', '$nin']) {
         for (const val of invalidValues) {
           await expect(
-            vectorDB.query(testIndexName, [1, 0, 0], 10, {
-              field: { [op]: val },
+            vectorDB.query({
+              indexName: testIndexName,
+              queryVector: [1, 0, 0],
+              filter: { field: { [op]: val } },
             }),
           ).rejects.toThrow();
         }
@@ -256,8 +389,10 @@ describe('ChromaVector Integration Tests', () => {
       // Basic equality can accept any non-undefined value
       for (const op of ['$eq', '$ne']) {
         await expect(
-          vectorDB.query(testIndexName, [1, 0, 0], 10, {
-            field: { [op]: undefined },
+          vectorDB.query({
+            indexName: testIndexName,
+            queryVector: [1, 0, 0],
+            filter: { field: { [op]: undefined } },
           }),
         ).rejects.toThrow();
       }
@@ -268,8 +403,10 @@ describe('ChromaVector Integration Tests', () => {
       for (const op of numOps) {
         for (const val of invalidNumericValues) {
           await expect(
-            vectorDB.query(testIndexName, [1, 0, 0], 10, {
-              field: { [op]: val },
+            vectorDB.query({
+              indexName: testIndexName,
+              queryVector: [1, 0, 0],
+              filter: { field: { [op]: val } },
             }),
           ).rejects.toThrow();
         }
@@ -278,29 +415,45 @@ describe('ChromaVector Integration Tests', () => {
 
     it('validates multiple invalid values', async () => {
       await expect(
-        vectorDB.query(testIndexName, [1, 0, 0], 10, {
-          field1: { $in: 'not-array' },
-          field2: { $exists: 'not-boolean' },
-          field3: { $gt: 'not-number' },
+        vectorDB.query({
+          indexName: testIndexName,
+          queryVector: [1, 0, 0],
+          filter: {
+            field1: { $in: 'not-array' },
+            field2: { $exists: 'not-boolean' },
+            field3: { $gt: 'not-number' },
+          },
         }),
       ).rejects.toThrow();
     });
 
     it('handles empty object filters', async () => {
       // Test empty object at top level
-      await expect(vectorDB.query(testIndexName, [1, 0, 0], 10, { field: { $eq: {} } })).rejects.toThrow();
+      await expect(
+        vectorDB.query({
+          indexName: testIndexName,
+          queryVector: [1, 0, 0],
+          filter: { field: { $eq: {} } },
+        }),
+      ).rejects.toThrow();
     });
 
     it('handles empty/undefined filters by returning all results', async () => {
       const noFilterCases = [{ field: {} }, { field: undefined }, { field: { $in: undefined } }];
 
       for (const filter of noFilterCases) {
-        await expect(vectorDB.query(testIndexName, [1, 0, 0], 10, filter)).rejects.toThrow();
+        await expect(vectorDB.query({ indexName: testIndexName, queryVector: [1, 0, 0], filter })).rejects.toThrow();
       }
     });
     it('handles empty object filters', async () => {
       // Test empty object at top level
-      await expect(vectorDB.query(testIndexName, [1, 0, 0], 10, {})).rejects.toThrow();
+      await expect(
+        vectorDB.query({
+          indexName: testIndexName,
+          queryVector: [1, 0, 0],
+          filter: {},
+        }),
+      ).rejects.toThrow();
     });
   });
 
@@ -309,10 +462,10 @@ describe('ChromaVector Integration Tests', () => {
     beforeAll(async () => {
       try {
         await vectorDB.deleteIndex(testIndexName2);
-      } catch (error) {
+      } catch {
         // Ignore errors if index doesn't exist
       }
-      await vectorDB.createIndex(testIndexName2, dimension);
+      await vectorDB.createIndex({ indexName: testIndexName2, dimension });
 
       const vectors = [
         [1, 0, 0], // Electronics
@@ -348,7 +501,7 @@ describe('ChromaVector Integration Tests', () => {
         },
       ];
 
-      await vectorDB.upsert(testIndexName2, vectors, metadata);
+      await vectorDB.upsert({ indexName: testIndexName2, vectors, metadata });
       // Wait for indexing
       await new Promise(resolve => setTimeout(resolve, 2000));
     });
@@ -357,15 +510,17 @@ describe('ChromaVector Integration Tests', () => {
       // Cleanup after tests
       try {
         await vectorDB.deleteIndex(testIndexName2);
-      } catch (error) {
+      } catch {
         // Ignore cleanup errors
       }
     });
 
     describe('Basic Comparison Operators', () => {
       it('filters with $eq operator', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          category: { $eq: 'electronics' },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { category: { $eq: 'electronics' } },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -374,8 +529,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('filters with implicit $eq', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          category: 'electronics', // implicit $eq
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { category: 'electronics' }, // implicit $eq
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -383,8 +540,10 @@ describe('ChromaVector Integration Tests', () => {
         });
       });
       it('filters with $gt operator', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          price: { $gt: 500 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { price: { $gt: 500 } },
         });
         expect(results.length).toBe(1);
         results.forEach(result => {
@@ -393,8 +552,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('filters with $gte operator', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          price: { $gte: 500 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { price: { $gte: 500 } },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -403,8 +564,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('filters with $lt operator', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          price: { $lt: 100 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { price: { $lt: 100 } },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -413,8 +576,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('filters with $lte operator', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          price: { $lte: 500 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { price: { $lte: 500 } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -423,8 +588,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('filters with $gte, $lt, $lte operators', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          price: { $gte: 25, $lte: 500 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { price: { $gte: 25, $lte: 500 } },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -434,8 +601,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('filters with $ne operator', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          category: { $ne: 'electronics' },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { category: { $ne: 'electronics' } },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -444,8 +613,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('filters with boolean values', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          inStock: true, // test both implicit
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { inStock: true }, // test both implicit
         });
         expect(results.length).toBe(3);
         results.forEach(result => {
@@ -454,9 +625,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('filters with multiple fields', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          category: 'electronics',
-          price: 1000,
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { category: 'electronics', price: 1000 },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -467,8 +639,10 @@ describe('ChromaVector Integration Tests', () => {
 
     describe('Array Operators', () => {
       it('filters with $in operator', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          category: { $in: ['electronics', 'books'] },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { category: { $in: ['electronics', 'books'] } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -477,8 +651,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('should filter with $in operator for numbers', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          price: { $in: [50, 75, 1000] },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { price: { $in: [50, 75, 1000] } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -487,8 +663,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('filters with $in operator for booleans', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          inStock: { $in: [true] },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { inStock: { $in: [true] } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -499,8 +677,10 @@ describe('ChromaVector Integration Tests', () => {
 
     describe('Logical Operators', () => {
       it('filters with $and operator', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $and: [{ category: 'electronics' }, { price: { $gt: 500 } }],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { $and: [{ category: 'electronics' }, { price: { $gt: 500 } }] },
         });
         expect(results.length).toBe(1);
         expect(results[0]?.metadata?.category).toBe('electronics');
@@ -508,8 +688,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('should filter with $and operator', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $and: [{ category: 'electronics' }, { price: { $gt: 700 } }, { inStock: true }],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { $and: [{ category: 'electronics' }, { price: { $gt: 700 } }, { inStock: true }] },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -520,8 +702,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('filters with $or operator', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $or: [{ price: { $gt: 900 } }, { rating: { $gt: 4.8 } }],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { $or: [{ price: { $gt: 900 } }, { rating: { $gt: 4.8 } }] },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -530,8 +714,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('should filter with $or operator', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $or: [{ price: { $gt: 900 } }, { category: { $in: ['electronics', 'books'] } }],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { $or: [{ price: { $gt: 900 } }, { category: { $in: ['electronics', 'books'] } }] },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -542,14 +728,18 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('should handle nested logical operators', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $and: [
-            {
-              $or: [{ category: 'electronics' }, { category: 'books' }],
-            },
-            { price: { $lt: 100 } },
-            { inStock: true },
-          ],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: {
+            $and: [
+              {
+                $or: [{ category: 'electronics' }, { category: 'books' }],
+              },
+              { price: { $lt: 100 } },
+              { inStock: true },
+            ],
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -560,37 +750,45 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('uses implicit $eq within $or', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $or: [{ category: 'electronics' }, { price: { $gt: 100 } }],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { $or: [{ category: 'electronics' }, { price: { $gt: 100 } }] },
         });
         expect(results.length).toBeGreaterThan(0);
       });
 
-      it('requires multiple conditions in logical operators', async () => {
-        await expect(
-          vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-            $and: [{ category: 'electronics' }],
-          }),
-        ).rejects.toThrow();
+      it('accepts single conditions in logical operators', async () => {
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { $and: [{ category: 'electronics' }] },
+        });
+        expect(results.length).toBeGreaterThan(0);
 
-        await expect(
-          vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-            $or: [{ price: { $gt: 900 } }],
-          }),
-        ).rejects.toThrow();
+        const results2 = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { $or: [{ price: { $gt: 900 } }] },
+        });
+        expect(results2.length).toBeGreaterThan(0);
       });
     });
 
     describe('Complex Filter Combinations', () => {
       it('combines multiple operators and conditions', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $and: [
-            { price: { $gt: 20 } },
-            { inStock: true },
-            {
-              $or: [{ category: { $in: ['books'] } }, { rating: { $gt: 4.5 } }],
-            },
-          ],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: {
+            $and: [
+              { price: { $gt: 20 } },
+              { inStock: true },
+              {
+                $or: [{ category: { $in: ['books'] } }, { rating: { $gt: 4.5 } }],
+              },
+            ],
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -601,15 +799,19 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('handles complex nested conditions', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $or: [
-            {
-              $and: [{ category: 'electronics' }, { price: { $gt: 700 } }],
-            },
-            {
-              $and: [{ category: 'books' }, { price: { $lt: 20 } }],
-            },
-          ],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: {
+            $or: [
+              {
+                $and: [{ category: 'electronics' }, { price: { $gt: 700 } }],
+              },
+              {
+                $and: [{ category: 'books' }, { price: { $lt: 20 } }],
+              },
+            ],
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -622,8 +824,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('should combine comparison and array operators', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $and: [{ price: { $gte: 500 } }, { rating: { $gt: 4.5 } }],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { $and: [{ price: { $gte: 500 } }, { rating: { $gt: 4.5 } }] },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -633,8 +837,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('should handle multiple conditions on same field', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $and: [{ price: { $gte: 30 } }, { price: { $lte: 800 } }],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { $and: [{ price: { $gte: 30 } }, { price: { $lte: 800 } }] },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -645,15 +851,19 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('should handle deeply nested logical operators', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $or: [
-            {
-              $and: [{ category: 'electronics' }, { price: { $gt: 700 } }, { rating: { $gt: 4.5 } }],
-            },
-            {
-              $and: [{ category: 'books' }, { price: { $lt: 50 } }, { rating: { $gt: 4.0 } }],
-            },
-          ],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: {
+            $or: [
+              {
+                $and: [{ category: 'electronics' }, { price: { $gt: 700 } }, { rating: { $gt: 4.5 } }],
+              },
+              {
+                $and: [{ category: 'books' }, { price: { $lt: 50 } }, { rating: { $gt: 4.0 } }],
+              },
+            ],
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -701,13 +911,19 @@ describe('ChromaVector Integration Tests', () => {
           },
         ];
 
-        await vectorDB.upsert(testIndexName2, vectors, metadata);
+        await vectorDB.upsert({
+          indexName: testIndexName2,
+          vectors,
+          metadata,
+        });
         await new Promise(resolve => setTimeout(resolve, 2000));
       });
 
       it('handles special numeric values', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $or: [{ zero: 0 }, { negativeZero: 0 }],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { $or: [{ zero: 0 }, { negativeZero: 0 }] },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -717,15 +933,23 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('handles extreme numeric values', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $or: [{ maxInt: { $gte: Number.MAX_SAFE_INTEGER } }, { minInt: { $lte: Number.MIN_SAFE_INTEGER } }],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: {
+            $or: [{ maxInt: { $gte: Number.MAX_SAFE_INTEGER } }, { minInt: { $lte: Number.MIN_SAFE_INTEGER } }],
+          },
         });
         expect(results.length).toBe(1);
       });
 
       it('should handle numeric comparisons with decimals', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          rating: { $gt: 4.5 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: {
+            rating: { $gt: 4.5 },
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -734,8 +958,10 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('should handle boolean values', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          inStock: { $eq: false },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: { inStock: { $eq: false } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -747,46 +973,76 @@ describe('ChromaVector Integration Tests', () => {
     describe('Additional Validation Tests', () => {
       it('should throw error as date is not supported', async () => {
         await expect(
-          vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-            $and: [
-              { currentDate: { $lte: new Date().toISOString() } },
-              { currentDate: { $gt: new Date(0).toISOString() } },
-            ],
+          vectorDB.query({
+            indexName: testIndexName2,
+            queryVector: [1, 0, 0],
+            filter: {
+              $and: [
+                { currentDate: { $lte: new Date().toISOString() } },
+                { currentDate: { $gt: new Date(0).toISOString() } },
+              ],
+            },
           }),
         ).rejects.toThrow();
       });
       it('should throw error as empty array in $in operator is not supported', async () => {
         await expect(
-          vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-            category: { $in: [] },
+          vectorDB.query({
+            indexName: testIndexName2,
+            queryVector: [1, 0, 0],
+            filter: {
+              category: { $in: [] },
+            },
           }),
         ).rejects.toThrow();
       });
       it('should reject non-numeric values in numeric comparisons', async () => {
         await expect(
-          vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-            price: { $gt: '500' }, // string instead of number
+          vectorDB.query({
+            indexName: testIndexName2,
+            queryVector: [1, 0, 0],
+            filter: {
+              price: { $gt: '500' }, // string instead of number
+            },
           }),
         ).rejects.toThrow();
       });
 
       it('should reject mixed types in $in operator', async () => {
         await expect(
-          vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-            field: { $in: ['string', 123] }, // mixed string and number
+          vectorDB.query({
+            indexName: testIndexName2,
+            queryVector: [1, 0, 0],
+            filter: {
+              field: { $in: ['string', 123] }, // mixed string and number
+            },
           }),
         ).rejects.toThrow();
       });
       it('should handle undefined filter', async () => {
-        const results1 = await vectorDB.query(testIndexName2, [1, 0, 0], 10, undefined);
-        const results2 = await vectorDB.query(testIndexName2, [1, 0, 0], 10);
+        const results1 = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: undefined,
+        });
+        const results2 = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+        });
         expect(results1).toEqual(results2);
         expect(results1.length).toBeGreaterThan(0);
       });
 
       it('should handle null filter', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, null as any);
-        const results2 = await vectorDB.query(testIndexName2, [1, 0, 0], 10);
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: null,
+        });
+        const results2 = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+        });
         expect(results).toEqual(results2);
         expect(results.length).toBeGreaterThan(0);
       });
@@ -794,8 +1050,12 @@ describe('ChromaVector Integration Tests', () => {
 
     describe('Additional Edge Cases', () => {
       it('should handle exact boundary conditions', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $and: [{ price: { $gte: 25 } }, { price: { $lte: 1000 } }],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: {
+            $and: [{ price: { $gte: 25 } }, { price: { $lte: 1000 } }],
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         expect(results.some(r => r.metadata?.price === 25)).toBe(true);
@@ -805,15 +1065,19 @@ describe('ChromaVector Integration Tests', () => {
 
     describe('Additional Complex Logical Combinations', () => {
       it('should handle deeply nested $or conditions', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $or: [
-            {
-              $and: [{ category: 'electronics' }, { $or: [{ price: { $gt: 900 } }, { rating: { $gt: 4.8 } }] }],
-            },
-            {
-              $and: [{ category: 'books' }, { $or: [{ price: { $lt: 30 } }, { rating: { $gt: 4.5 } }] }],
-            },
-          ],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: {
+            $or: [
+              {
+                $and: [{ category: 'electronics' }, { $or: [{ price: { $gt: 900 } }, { rating: { $gt: 4.8 } }] }],
+              },
+              {
+                $and: [{ category: 'books' }, { $or: [{ price: { $lt: 30 } }, { rating: { $gt: 4.5 } }] }],
+              },
+            ],
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -826,8 +1090,12 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('should handle multiple field comparisons with same value', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $or: [{ price: { $gt: 500 } }, { rating: { $gt: 4.5 } }],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: {
+            $or: [{ price: { $gt: 500 } }, { rating: { $gt: 4.5 } }],
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -838,12 +1106,16 @@ describe('ChromaVector Integration Tests', () => {
 
     describe('Performance Edge Cases', () => {
       it('should handle filters with many conditions', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $and: Array(10)
-            .fill(null)
-            .map(() => ({
-              $or: [{ price: { $gt: 100 } }, { rating: { $gt: 4.0 } }],
-            })),
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: {
+            $and: Array(10)
+              .fill(null)
+              .map(() => ({
+                $or: [{ price: { $gt: 100 } }, { rating: { $gt: 4.0 } }],
+              })),
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -852,12 +1124,20 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('should handle deeply nested conditions efficiently', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $or: Array(5)
-            .fill(null)
-            .map(() => ({
-              $and: [{ category: { $in: ['electronics', 'books'] } }, { price: { $gt: 50 } }, { rating: { $gt: 4.0 } }],
-            })),
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: {
+            $or: Array(5)
+              .fill(null)
+              .map(() => ({
+                $and: [
+                  { category: { $in: ['electronics', 'books'] } },
+                  { price: { $gt: 50 } },
+                  { rating: { $gt: 4.0 } },
+                ],
+              })),
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -868,22 +1148,452 @@ describe('ChromaVector Integration Tests', () => {
       });
 
       it('should handle large number of $or conditions', async () => {
-        const results = await vectorDB.query(testIndexName2, [1, 0, 0], 10, {
-          $or: [
-            ...Array(5)
-              .fill(null)
-              .map((_, i) => ({
-                price: { $gt: i * 100 },
-              })),
-            ...Array(5)
-              .fill(null)
-              .map((_, i) => ({
-                rating: { $gt: 4.0 + i * 0.1 },
-              })),
-          ],
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: [1, 0, 0],
+          filter: {
+            $or: [
+              ...Array(5)
+                .fill(null)
+                .map((_, i) => ({
+                  price: { $gt: i * 100 },
+                })),
+              ...Array(5)
+                .fill(null)
+                .map((_, i) => ({
+                  rating: { $gt: 4.0 + i * 0.1 },
+                })),
+            ],
+          },
+        });
+        expect(results.length).toBeGreaterThan(0);
+      });
+    });
+  });
+
+  describe('Document Operations and Filtering', () => {
+    const testDocuments = [
+      'The quick brown fox jumps over the lazy dog',
+      'Pack my box with five dozen liquor jugs',
+      'How vexingly quick daft zebras JUMP',
+    ];
+
+    beforeAll(async () => {
+      try {
+        await vectorDB.deleteIndex(testIndexName3);
+      } catch {
+        // Ignore errors if index doesn't exist
+      }
+      await vectorDB.createIndex({ indexName: testIndexName3, dimension });
+
+      const testVectors = [
+        [1.0, 0.0, 0.0],
+        [0.0, 1.0, 0.0],
+        [0.0, 0.0, 1.0],
+      ];
+
+      const testMetadata = [
+        { source: 'pangram1', length: 43 },
+        { source: 'pangram2', length: 32 },
+        { source: 'pangram3', length: 30 },
+      ];
+      const testIds = ['doc1', 'doc2', 'doc3'];
+
+      await vectorDB.upsert({
+        indexName: testIndexName3,
+        vectors: testVectors,
+        documents: testDocuments,
+        metadata: testMetadata,
+        ids: testIds,
+      });
+
+      // Wait for indexing
+      await new Promise(resolve => setTimeout(resolve, 2000));
+    });
+
+    afterAll(async () => {
+      // Cleanup after tests
+      try {
+        await vectorDB.deleteIndex(testIndexName3);
+      } catch {
+        // Ignore cleanup errors
+      }
+    });
+
+    describe('Basic Document Operations', () => {
+      it('should store and retrieve documents', async () => {
+        const results = await vectorDB.query({ indexName: testIndexName3, queryVector: [1.0, 0.0, 0.0], topK: 3 });
+        expect(results).toHaveLength(3);
+        // Verify documents are returned
+        expect(results[0].document).toBe(testDocuments[0]);
+      });
+
+      it('should filter documents using $contains', async () => {
+        const results = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1.0, 0.0, 0.0],
+          topK: 3,
+          documentFilter: { $contains: 'quick' },
+        });
+        expect(results).toHaveLength(2);
+      });
+
+      it('should filter with $not_contains', async () => {
+        const results = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1.0, 0.0, 0.0],
+          topK: 3,
+          documentFilter: { $not_contains: 'fox' },
+        });
+        expect(results.every(r => !r.document?.includes('fox'))).toBe(true);
+      });
+
+      it('should combine metadata and document filters', async () => {
+        const results = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1.0, 0.0, 0.0],
+          topK: 3,
+          filter: { source: 'pangram1' },
+          documentFilter: { $contains: 'fox' },
+        });
+        expect(results).toHaveLength(1);
+        expect(results[0].metadata?.source).toBe('pangram1');
+        expect(results[0].document).toContain('fox');
+      });
+    });
+
+    describe('Complex Document Filtering', () => {
+      it('should handle $and conditions', async () => {
+        const results = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1.0, 0.0, 0.0],
+          topK: 3,
+          documentFilter: { $and: [{ $contains: 'quick' }, { $not_contains: 'fox' }] },
+        });
+        expect(results).toHaveLength(1);
+        expect(results[0].document).toContain('quick');
+        expect(results[0].document).not.toContain('fox');
+      });
+
+      it('should handle $or conditions', async () => {
+        const results = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1.0, 0.0, 0.0],
+          topK: 3,
+          documentFilter: { $or: [{ $contains: 'fox' }, { $contains: 'zebras' }] },
+        });
+        expect(results).toHaveLength(2);
+        expect(results[0].document).toContain('fox');
+        expect(results[1].document).toContain('zebras');
+      });
+    });
+
+    describe('Edge Cases and Validation', () => {
+      it('allows empty string in $contains', async () => {
+        const results = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1.0, 0.0, 0.0],
+          topK: 3,
+          documentFilter: { $contains: '' },
+        });
+        expect(results).toHaveLength(3);
+      });
+
+      it('should be case sensitive', async () => {
+        // First verify lowercase works
+        const lowerResults = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1.0, 0.0, 0.0],
+          topK: 3,
+          documentFilter: { $contains: 'quick' },
+        });
+        expect(lowerResults.length).toBe(2);
+
+        // Then verify uppercase doesn't match
+        const upperResults = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1.0, 0.0, 0.0],
+          topK: 3,
+          documentFilter: { $contains: 'QUICK' },
+        });
+        expect(upperResults.length).toBe(0);
+
+        const upperResults2 = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1.0, 0.0, 0.0],
+          topK: 3,
+          documentFilter: { $contains: 'JUMP' },
+        });
+        expect(upperResults2.length).toBe(1);
+      });
+
+      it('should handle exact string matches', async () => {
+        const results = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1.0, 0.0, 0.0],
+          topK: 3,
+          documentFilter: { $contains: 'quick brown' }, // Test multi-word match
         });
+        expect(results.length).toBe(1);
+        expect(results[0].document).toContain('quick brown');
+      });
+
+      it('should handle deeply nested logical operators', async () => {
+        const results = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1.0, 0.0, 0.0],
+          topK: 3,
+          documentFilter: {
+            $or: [
+              {
+                $and: [{ $contains: 'quick' }, { $not_contains: 'fox' }],
+              },
+              {
+                $and: [{ $contains: 'box' }, { $not_contains: 'quick' }],
+              },
+            ],
+          },
+        });
+        expect(results.length).toBeGreaterThan(0);
+        results.forEach(result => {
+          if (result.document?.includes('quick')) {
+            expect(result.document).not.toContain('fox');
+          } else if (result.document?.includes('box')) {
+            expect(result.document).not.toContain('quick');
+          }
+        });
+      });
+      it('should handle undefined document filter', async () => {
+        const results1 = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1, 0, 0],
+          documentFilter: undefined,
+        });
+        const results2 = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1, 0, 0],
+        });
+        expect(results1).toEqual(results2);
+        expect(results1.length).toBeGreaterThan(0);
+      });
+
+      it('should handle empty object document filter', async () => {
+        await expect(
+          vectorDB.query({
+            indexName: testIndexName3,
+            queryVector: [1, 0, 0],
+            documentFilter: {},
+          }),
+        ).rejects.toThrow();
+      });
+
+      it('should handle null filter', async () => {
+        const results = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1, 0, 0],
+          documentFilter: null,
+        });
+        const results2 = await vectorDB.query({
+          indexName: testIndexName3,
+          queryVector: [1, 0, 0],
+        });
+        expect(results).toEqual(results2);
         expect(results.length).toBeGreaterThan(0);
       });
     });
   });
+  describe('Deprecation Warnings', () => {
+    const indexName = 'testdeprecationwarnings';
+
+    const indexName2 = 'testdeprecationwarnings2';
+
+    let warnSpy;
+
+    beforeAll(async () => {
+      await vectorDB.createIndex({ indexName: indexName, dimension: 3 });
+    });
+
+    afterAll(async () => {
+      try {
+        await vectorDB.deleteIndex(indexName);
+      } catch {
+        // Ignore errors if index doesn't exist
+      }
+      try {
+        await vectorDB.deleteIndex(indexName2);
+      } catch {
+        // Ignore errors if index doesn't exist
+      }
+    });
+
+    beforeEach(async () => {
+      warnSpy = vi.spyOn(vectorDB['logger'], 'warn');
+    });
+
+    afterEach(async () => {
+      warnSpy.mockRestore();
+      try {
+        await vectorDB.deleteIndex(indexName2);
+      } catch {
+        // Ignore errors if index doesn't exist
+      }
+    });
+
+    it('should show deprecation warning when using individual args for createIndex', async () => {
+      await vectorDB.createIndex(indexName2, 3, 'cosine');
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Deprecation Warning: Passing individual arguments to createIndex() is deprecated'),
+      );
+    });
+
+    it('should show deprecation warning when using individual args for upsert', async () => {
+      await vectorDB.upsert(indexName, [[1, 2, 3]], [{ test: 'data' }]);
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Deprecation Warning: Passing individual arguments to upsert() is deprecated'),
+      );
+    });
+
+    it('should show deprecation warning when using individual args for query', async () => {
+      await vectorDB.query(indexName, [1, 2, 3], 5);
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Deprecation Warning: Passing individual arguments to query() is deprecated'),
+      );
+    });
+
+    it('should not show deprecation warning when using object param for query', async () => {
+      await vectorDB.query({
+        indexName,
+        queryVector: [1, 2, 3],
+        topK: 5,
+      });
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should not show deprecation warning when using object param for createIndex', async () => {
+      await vectorDB.createIndex({
+        indexName: indexName2,
+        dimension: 3,
+        metric: 'cosine',
+      });
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should not show deprecation warning when using object param for upsert', async () => {
+      await vectorDB.upsert({
+        indexName,
+        vectors: [[1, 2, 3]],
+        metadata: [{ test: 'data' }],
+      });
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should maintain backward compatibility with individual args', async () => {
+      // Query
+      const queryResults = await vectorDB.query(indexName, [1, 2, 3], 5);
+      expect(Array.isArray(queryResults)).toBe(true);
+
+      // CreateIndex
+      await expect(vectorDB.createIndex(indexName2, 3, 'cosine')).resolves.not.toThrow();
+
+      // Upsert
+      const upsertResults = await vectorDB.upsert({
+        indexName,
+        vectors: [[1, 2, 3]],
+        metadata: [{ test: 'data' }],
+      });
+      expect(Array.isArray(upsertResults)).toBe(true);
+      expect(upsertResults).toHaveLength(1);
+    });
+  });
+
+  describe('Performance and Concurrency', () => {
+    const perfTestIndex = 'perf-test-index';
+
+    beforeEach(async () => {
+      try {
+        await vectorDB.deleteIndex(perfTestIndex);
+      } catch {
+        // Ignore errors if index doesn't exist
+      }
+      await vectorDB.createIndex({ indexName: perfTestIndex, dimension });
+    }, 10000);
+
+    afterEach(async () => {
+      try {
+        await vectorDB.deleteIndex(perfTestIndex);
+      } catch {
+        // Ignore cleanup errors
+      }
+    }, 10000);
+
+    it('handles concurrent operations correctly', async () => {
+      const promises = Array(10)
+        .fill(0)
+        .map((_, i) =>
+          vectorDB.upsert({
+            indexName: perfTestIndex,
+            vectors: [[1, 0, 0]],
+            metadata: [{ test: 'concurrent', id: i }],
+            ids: [`concurrent-${i}`],
+          }),
+        );
+      await Promise.all(promises);
+
+      const results = await vectorDB.query({
+        indexName: perfTestIndex,
+        queryVector: [1, 0, 0],
+        filter: { test: 'concurrent' },
+      });
+      expect(results).toHaveLength(10);
+    }, 15000);
+
+    it('handles large batch operations', async () => {
+      const batchSize = 100; // Using 100 instead of 1000 to keep tests fast
+      const vectors = Array(batchSize)
+        .fill(0)
+        .map(() => [1, 0, 0]);
+      const metadata = vectors.map((_, i) => ({ index: i, test: 'batch' }));
+      const ids = vectors.map((_, i) => `batch-${i}`);
+
+      await vectorDB.upsert({
+        indexName: perfTestIndex,
+        vectors,
+        metadata,
+        ids,
+      });
+
+      // Verify all vectors were inserted
+      const stats = await vectorDB.describeIndex(perfTestIndex);
+      expect(stats.count).toBe(batchSize);
+
+      const results = await vectorDB.query({
+        indexName: perfTestIndex,
+        queryVector: [1, 0, 0],
+        filter: { test: 'batch' },
+        topK: batchSize,
+      });
+      expect(results).toHaveLength(batchSize);
+
+      // Test querying with pagination
+      const pageSize = 20;
+      const pages: QueryResult[][] = [];
+      for (let i = 0; i < batchSize; i += pageSize) {
+        const page = await vectorDB.query({
+          indexName: perfTestIndex,
+          queryVector: [1, 0, 0],
+          filter: { test: 'batch' },
+          topK: pageSize,
+        });
+        pages.push(page);
+        expect(page).toHaveLength(Math.min(pageSize, batchSize - i));
+      }
+      expect(pages).toHaveLength(Math.ceil(batchSize / pageSize));
+    }, 30000);
+  });
 });