@mastra/pg 0.1.6-alpha.1 → 0.1.6-alpha.4

package/src/vector/index.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach, vi } from 'vitest';
 
 import { PgVector } from '.';
 
@@ -27,32 +27,39 @@ describe('PgVector', () => {
       });
 
       it('should create a new vector table with specified dimensions', async () => {
-        await vectorDB.createIndex(testIndexName, 3);
+        await vectorDB.createIndex({ indexName: testIndexName, dimension: 3 });
         const stats = await vectorDB.describeIndex(testIndexName);
         expect(stats?.dimension).toBe(3);
         expect(stats?.count).toBe(0);
       });
 
       it('should create index with specified metric', async () => {
-        await vectorDB.createIndex(testIndexName2, 3, 'euclidean');
+        await vectorDB.createIndex({ indexName: testIndexName2, dimension: 3, metric: 'euclidean' });
         const stats = await vectorDB.describeIndex(testIndexName2);
         expect(stats.metric).toBe('euclidean');
       });
 
       it('should throw error if dimension is invalid', async () => {
-        await expect(vectorDB.createIndex(`testIndexNameFail`, 0)).rejects.toThrow();
+        await expect(vectorDB.createIndex({ indexName: 'testIndexNameFail', dimension: 0 })).rejects.toThrow();
       });
 
       it('should create index with flat type', async () => {
-        await vectorDB.createIndex(testIndexName2, 3, 'cosine', { type: 'flat' });
+        await vectorDB.createIndex({
+          indexName: testIndexName2,
+          dimension: 3,
+          metric: 'cosine',
+          indexConfig: { type: 'flat' },
+        });
         const stats = await vectorDB.describeIndex(testIndexName2);
         expect(stats.type).toBe('flat');
       });
 
       it('should create index with hnsw type', async () => {
-        await vectorDB.createIndex(testIndexName2, 3, 'cosine', {
-          type: 'hnsw',
-          hnsw: { m: 16, efConstruction: 64 }, // Any reasonable values work
+        await vectorDB.createIndex({
+          indexName: testIndexName2,
+          dimension: 3,
+          metric: 'cosine',
+          indexConfig: { type: 'hnsw', hnsw: { m: 16, efConstruction: 64 } }, // Any reasonable values work
         });
         const stats = await vectorDB.describeIndex(testIndexName2);
         expect(stats.type).toBe('hnsw');
@@ -60,9 +67,11 @@ describe('PgVector', () => {
       });
 
       it('should create index with ivfflat type and lists', async () => {
-        await vectorDB.createIndex(testIndexName2, 3, 'cosine', {
-          type: 'ivfflat',
-          ivf: { lists: 100 },
+        await vectorDB.createIndex({
+          indexName: testIndexName2,
+          dimension: 3,
+          metric: 'cosine',
+          indexConfig: { type: 'ivfflat', ivf: { lists: 100 } },
         });
         const stats = await vectorDB.describeIndex(testIndexName2);
         expect(stats.type).toBe('ivfflat');
@@ -73,7 +82,7 @@ describe('PgVector', () => {
     describe('listIndexes', () => {
       const indexName = 'test_query_3';
       beforeAll(async () => {
-        await vectorDB.createIndex(indexName, 3);
+        await vectorDB.createIndex({ indexName, dimension: 3 });
       });
 
       afterAll(async () => {
@@ -95,7 +104,7 @@ describe('PgVector', () => {
     describe('describeIndex', () => {
       const indexName = 'test_query_4';
       beforeAll(async () => {
-        await vectorDB.createIndex(indexName, 3);
+        await vectorDB.createIndex({ indexName, dimension: 3 });
       });
 
       afterAll(async () => {
@@ -103,12 +112,12 @@ describe('PgVector', () => {
       });
 
       it('should return correct index stats', async () => {
-        await vectorDB.createIndex(indexName, 3, 'cosine');
+        await vectorDB.createIndex({ indexName, dimension: 3, metric: 'cosine' });
         const vectors = [
           [1, 2, 3],
           [4, 5, 6],
         ];
-        await vectorDB.upsert(indexName, vectors);
+        await vectorDB.upsert({ indexName, vectors });
 
         const stats = await vectorDB.describeIndex(indexName);
         expect(stats).toEqual({
@@ -126,13 +135,50 @@ describe('PgVector', () => {
         await expect(vectorDB.describeIndex('non_existent')).rejects.toThrow();
       });
     });
+
+    describe('buildIndex', () => {
+      const indexName = 'test_build_index';
+      beforeAll(async () => {
+        await vectorDB.createIndex({ indexName, dimension: 3 });
+      });
+
+      afterAll(async () => {
+        await vectorDB.deleteIndex(indexName);
+      });
+
+      it('should build index with specified metric and config', async () => {
+        await vectorDB.buildIndex({
+          indexName,
+          metric: 'cosine',
+          indexConfig: { type: 'hnsw', hnsw: { m: 16, efConstruction: 64 } },
+        });
+
+        const stats = await vectorDB.describeIndex(indexName);
+        expect(stats.type).toBe('hnsw');
+        expect(stats.metric).toBe('cosine');
+        expect(stats.config.m).toBe(16);
+      });
+
+      it('should build ivfflat index with specified lists', async () => {
+        await vectorDB.buildIndex({
+          indexName,
+          metric: 'euclidean',
+          indexConfig: { type: 'ivfflat', ivf: { lists: 100 } },
+        });
+
+        const stats = await vectorDB.describeIndex(indexName);
+        expect(stats.type).toBe('ivfflat');
+        expect(stats.metric).toBe('euclidean');
+        expect(stats.config.lists).toBe(100);
+      });
+    });
   });
 
   // Vector Operations Tests
   describe('Vector Operations', () => {
     describe('upsert', () => {
       beforeEach(async () => {
-        await vectorDB.createIndex(testIndexName, 3);
+        await vectorDB.createIndex({ indexName: testIndexName, dimension: 3 });
       });
 
       afterEach(async () => {
@@ -144,7 +190,7 @@ describe('PgVector', () => {
           [1, 2, 3],
           [4, 5, 6],
         ];
-        const ids = await vectorDB.upsert(testIndexName, vectors);
+        const ids = await vectorDB.upsert({ indexName: testIndexName, vectors });
 
         expect(ids).toHaveLength(2);
         const stats = await vectorDB.describeIndex(testIndexName);
@@ -154,13 +200,18 @@ describe('PgVector', () => {
       it('should update existing vectors', async () => {
         const vectors = [[1, 2, 3]];
         const metadata = [{ test: 'initial' }];
-        const [id] = await vectorDB.upsert(testIndexName, vectors, metadata);
+        const [id] = await vectorDB.upsert({ indexName: testIndexName, vectors, metadata });
 
         const updatedVectors = [[4, 5, 6]];
         const updatedMetadata = [{ test: 'updated' }];
-        await vectorDB.upsert(testIndexName, updatedVectors, updatedMetadata, [id!]);
+        await vectorDB.upsert({
+          indexName: testIndexName,
+          vectors: updatedVectors,
+          metadata: updatedMetadata,
+          ids: [id!],
+        });
 
-        const results = await vectorDB.query(testIndexName, [4, 5, 6], 1);
+        const results = await vectorDB.query({ indexName: testIndexName, queryVector: [4, 5, 6], topK: 1 });
         expect(results[0]?.id).toBe(id);
         expect(results[0]?.metadata).toEqual({ test: 'updated' });
       });
@@ -169,15 +220,15 @@ describe('PgVector', () => {
         const vectors = [[1, 2, 3]];
         const metadata = [{ test: 'value', num: 123 }];
 
-        await vectorDB.upsert(testIndexName, vectors, metadata);
-        const results = await vectorDB.query(testIndexName, [1, 2, 3], 1);
+        await vectorDB.upsert({ indexName: testIndexName, vectors, metadata });
+        const results = await vectorDB.query({ indexName: testIndexName, queryVector: [1, 2, 3], topK: 1 });
 
         expect(results[0]?.metadata).toEqual(metadata[0]);
       });
 
       it('should throw error if vector dimensions dont match', async () => {
         const vectors = [[1, 2, 3, 4]]; // 4D vector for 3D index
-        await expect(vectorDB.upsert(testIndexName, vectors)).rejects.toThrow();
+        await expect(vectorDB.upsert({ indexName: testIndexName, vectors })).rejects.toThrow();
       });
     });
 
@@ -190,7 +241,7 @@ describe('PgVector', () => {
           } catch {
             // Ignore if doesn't exist
           }
-          await vectorDB.createIndex(indexName, 3);
+          await vectorDB.createIndex({ indexName, dimension: 3 });
         });
 
         beforeEach(async () => {
@@ -205,7 +256,7 @@ describe('PgVector', () => {
             { type: 'b', value: 2 },
             { type: 'a', value: 3 },
           ];
-          await vectorDB.upsert(indexName, vectors, metadata);
+          await vectorDB.upsert({ indexName, vectors, metadata });
         });
 
         afterAll(async () => {
@@ -213,25 +264,30 @@ describe('PgVector', () => {
         });
 
         it('should return closest vectors', async () => {
-          const results = await vectorDB.query(indexName, [1, 0, 0], 1);
+          const results = await vectorDB.query({ indexName, queryVector: [1, 0, 0], topK: 1 });
           expect(results).toHaveLength(1);
           expect(results[0]?.vector).toBe(undefined);
           expect(results[0]?.score).toBeCloseTo(1, 5);
         });
 
         it('should return vector with result', async () => {
-          const results = await vectorDB.query(indexName, [1, 0, 0], 1, undefined, true);
+          const results = await vectorDB.query({ indexName, queryVector: [1, 0, 0], topK: 1, includeVector: true });
           expect(results).toHaveLength(1);
           expect(results[0]?.vector).toStrictEqual([1, 0, 0]);
         });
 
         it('should respect topK parameter', async () => {
-          const results = await vectorDB.query(indexName, [1, 0, 0], 2);
+          const results = await vectorDB.query({ indexName, queryVector: [1, 0, 0], topK: 2 });
           expect(results).toHaveLength(2);
         });
 
         it('should handle filters correctly', async () => {
-          const results = await vectorDB.query(indexName, [1, 0, 0], 10, { type: 'a' });
+          const results = await vectorDB.query({
+            indexName,
+            queryVector: [1, 0, 0],
+            topK: 10,
+            filter: { type: 'a' },
+          });
 
           expect(results).toHaveLength(1);
           results.forEach(result => {
@@ -251,7 +307,7 @@ describe('PgVector', () => {
       } catch {
         // Ignore if doesn't exist
       }
-      await vectorDB.createIndex(indexName, 3);
+      await vectorDB.createIndex({ indexName, dimension: 3 });
     });
 
     beforeEach(async () => {
@@ -301,7 +357,7 @@ describe('PgVector', () => {
         { category: 'clothing', price: 60, tags: ['new'], active: true },
       ];
 
-      await vectorDB.upsert(indexName, vectors, metadata);
+      await vectorDB.upsert({ indexName, vectors, metadata });
     });
 
     afterAll(async () => {
@@ -312,26 +368,32 @@ describe('PgVector', () => {
     describe('Comparison Operators', () => {
       it('should handle numeric string comparisons', async () => {
         // Insert a record with numeric string
-        await vectorDB.upsert(indexName, [[1, 0.1, 0]], [{ numericString: '123' }]);
+        await vectorDB.upsert({ indexName, vectors: [[1, 0.1, 0]], metadata: [{ numericString: '123' }] });
 
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          numericString: { $gt: '100' }, // Compare strings numerically
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { numericString: { $gt: '100' } },
         });
         expect(results.length).toBeGreaterThan(0);
         expect(results[0]?.metadata?.numericString).toBe('123');
       });
 
       it('should filter with $gt operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          price: { $gt: 75 },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { price: { $gt: 75 } },
         });
         expect(results).toHaveLength(1);
         expect(results[0]?.metadata?.price).toBe(100);
       });
 
       it('should filter with $lte operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          price: { $lte: 50 },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { price: { $lte: 50 } },
         });
         expect(results).toHaveLength(2);
         results.forEach(result => {
@@ -340,8 +402,10 @@ describe('PgVector', () => {
       });
 
       it('should filter with lt operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          price: { $lt: 60 },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { price: { $lt: 60 } },
         });
         expect(results).toHaveLength(2);
         results.forEach(result => {
@@ -350,8 +414,10 @@ describe('PgVector', () => {
       });
 
       it('should filter with gte operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          price: { $gte: 75 },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { price: { $gte: 75 } },
         });
         expect(results).toHaveLength(2);
         results.forEach(result => {
@@ -360,8 +426,10 @@ describe('PgVector', () => {
       });
 
       it('should filter with ne operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: { $ne: 'electronics' },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: { $ne: 'electronics' } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -370,8 +438,10 @@ describe('PgVector', () => {
       });
 
       it('should filter with $gt and $lte operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          price: { $gt: 70, $lte: 100 },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { price: { $gt: 70, $lte: 100 } },
         });
         expect(results).toHaveLength(2);
         results.forEach(result => {
@@ -384,8 +454,10 @@ describe('PgVector', () => {
     // Array Operator Tests
     describe('Array Operators', () => {
       it('should filter with $in operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: { $in: ['electronics', 'clothing'] },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: { $in: ['electronics', 'clothing'] } },
         });
         expect(results).toHaveLength(3);
         results.forEach(result => {
@@ -394,8 +466,10 @@ describe('PgVector', () => {
       });
 
       it('should filter with $nin operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: { $nin: ['electronics', 'books'] },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: { $nin: ['electronics', 'books'] } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -405,21 +479,27 @@ describe('PgVector', () => {
 
       it('should handle empty arrays in in/nin operators', async () => {
         // Should return no results for empty IN
-        const resultsIn = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: { $in: [] },
+        const resultsIn = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: { $in: [] } },
         });
         expect(resultsIn).toHaveLength(0);
 
         // Should return all results for empty NIN
-        const resultsNin = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: { $nin: [] },
+        const resultsNin = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: { $nin: [] } },
         });
         expect(resultsNin.length).toBeGreaterThan(0);
       });
 
       it('should filter with array $contains operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0.1, 0], 10, {
-          tags: { $contains: ['new'] },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0.1, 0],
+          filter: { tags: { $contains: ['new'] } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -428,12 +508,10 @@ describe('PgVector', () => {
       });
 
       it('should filter with $elemMatch operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          tags: {
-            $elemMatch: {
-              $in: ['new', 'premium'],
-            },
-          },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { tags: { $elemMatch: { $in: ['new', 'premium'] } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -442,25 +520,20 @@ describe('PgVector', () => {
       });
 
       it('should filter with $elemMatch using equality', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          tags: {
-            $elemMatch: {
-              $eq: 'sale',
-            },
-          },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { tags: { $elemMatch: { $eq: 'sale' } } },
         });
         expect(results).toHaveLength(1);
         expect(results[0]?.metadata?.tags).toContain('sale');
       });
 
       it('should filter with $elemMatch using multiple conditions', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          ratings: {
-            $elemMatch: {
-              $gt: 4,
-              $lt: 4.5,
-            },
-          },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { ratings: { $elemMatch: { $gt: 4, $lt: 4.5 } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -470,13 +543,10 @@ describe('PgVector', () => {
       });
 
       it('should handle complex $elemMatch conditions', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          stock: {
-            $elemMatch: {
-              location: 'A',
-              count: { $gt: 20 },
-            },
-          },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { stock: { $elemMatch: { location: 'A', count: { $gt: 20 } } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -486,12 +556,10 @@ describe('PgVector', () => {
       });
 
       it('should filter with $elemMatch on nested numeric fields', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          reviews: {
-            $elemMatch: {
-              score: { $gt: 4 },
-            },
-          },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { reviews: { $elemMatch: { score: { $gt: 4 } } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -500,13 +568,10 @@ describe('PgVector', () => {
       });
 
       it('should filter with $elemMatch on multiple nested fields', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          reviews: {
-            $elemMatch: {
-              score: { $gte: 4 },
-              verified: true,
-            },
-          },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { reviews: { $elemMatch: { score: { $gte: 4 }, verified: true } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -515,31 +580,29 @@ describe('PgVector', () => {
       });
 
       it('should filter with $elemMatch on exact string match', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          reviews: {
-            $elemMatch: {
-              user: 'alice',
-            },
-          },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { reviews: { $elemMatch: { user: 'alice' } } },
         });
         expect(results).toHaveLength(1);
         expect(results[0].metadata?.reviews.some(r => r.user === 'alice')).toBe(true);
       });
 
       it('should handle $elemMatch with no matches', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          reviews: {
-            $elemMatch: {
-              score: 10, // No review has score 10
-            },
-          },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { reviews: { $elemMatch: { score: 10 } } },
         });
         expect(results).toHaveLength(0);
       });
 
       it('should filter with $all operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          tags: { $all: ['used', 'sale'] },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { tags: { $all: ['used', 'sale'] } },
         });
         expect(results).toHaveLength(1);
         results.forEach(result => {
@@ -549,8 +612,10 @@ describe('PgVector', () => {
       });
 
       it('should filter with $all using single value', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          tags: { $all: ['new'] },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { tags: { $all: ['new'] } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -559,26 +624,32 @@ describe('PgVector', () => {
       });
 
       it('should handle empty array for $all', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          tags: { $all: [] },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { tags: { $all: [] } },
         });
         expect(results).toHaveLength(0);
       });
 
       it('should handle non-array field $all', async () => {
         // First insert a record with non-array field
-        await vectorDB.upsert(indexName, [[1, 0.1, 0]], [{ tags: 'not-an-array' }]);
+        await vectorDB.upsert({ indexName, vectors: [[1, 0.1, 0]], metadata: [{ tags: 'not-an-array' }] });
 
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          tags: { $all: ['value'] },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { tags: { $all: ['value'] } },
         });
         expect(results).toHaveLength(0);
       });
 
       // Contains Operator Tests
       it('should filter with contains operator for exact field match', async () => {
-        const results = await vectorDB.query(indexName, [1, 0.1, 0], 10, {
-          category: { $contains: 'electronics' },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0.1, 0],
+          filter: { category: { $contains: 'electronics' } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -588,19 +659,21 @@ describe('PgVector', () => {
 
       it('should filter with $contains operator for nested objects', async () => {
         // First insert a record with nested object
-        await vectorDB.upsert(
+        await vectorDB.upsert({
           indexName,
-          [[1, 0.1, 0]],
-          [
+          vectors: [[1, 0.1, 0]],
+          metadata: [
             {
               details: { color: 'red', size: 'large' },
               category: 'clothing',
             },
           ],
-        );
+        });
 
-        const results = await vectorDB.query(indexName, [1, 0.1, 0], 10, {
-          details: { $contains: { color: 'red' } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0.1, 0],
+          filter: { details: { $contains: { color: 'red' } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -610,37 +683,47 @@ describe('PgVector', () => {
 
       // String Pattern Tests
       it('should handle exact string matches', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: 'electronics',
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: 'electronics' },
         });
         expect(results).toHaveLength(2);
       });
 
       it('should handle case-sensitive string matches', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: 'ELECTRONICS',
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: 'ELECTRONICS' },
         });
         expect(results).toHaveLength(0);
       });
       it('should filter arrays by size', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          ratings: { $size: 3 },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { ratings: { $size: 3 } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
           expect(result.metadata?.ratings).toHaveLength(3);
         });
 
-        const noResults = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          ratings: { $size: 10 },
+        const noResults = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { ratings: { $size: 10 } },
         });
         expect(noResults).toHaveLength(0);
       });
 
       it('should handle $size with nested arrays', async () => {
-        await vectorDB.upsert(indexName, [[1, 0.1, 0]], [{ nested: { array: [1, 2, 3, 4] } }]);
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          'nested.array': { $size: 4 },
+        await vectorDB.upsert({ indexName, vectors: [[1, 0.1, 0]], metadata: [{ nested: { array: [1, 2, 3, 4] } }] });
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { 'nested.array': { $size: 4 } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -652,8 +735,10 @@ describe('PgVector', () => {
     // Logical Operator Tests
     describe('Logical Operators', () => {
       it('should handle AND filter conditions', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $and: [{ category: { $eq: 'electronics' } }, { price: { $gt: 75 } }],
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $and: [{ category: { $eq: 'electronics' } }, { price: { $gt: 75 } }] },
         });
         expect(results).toHaveLength(1);
         expect(results[0]?.metadata?.category).toBe('electronics');
@@ -661,8 +746,10 @@ describe('PgVector', () => {
       });
 
       it('should handle OR filter conditions', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $or: [{ category: { $eq: 'electronics' } }, { category: { $eq: 'books' } }],
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $or: [{ category: { $eq: 'electronics' } }, { category: { $eq: 'books' } }] },
         });
         expect(results.length).toBeGreaterThan(1);
         results.forEach(result => {
@@ -671,8 +758,10 @@ describe('PgVector', () => {
       });
 
       it('should handle $not operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $not: { category: 'electronics' },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $not: { category: 'electronics' } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -681,8 +770,10 @@ describe('PgVector', () => {
       });
 
       it('should handle $nor operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $nor: [{ category: 'electronics' }, { category: 'books' }],
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $nor: [{ category: 'electronics' }, { category: 'books' }] },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -691,8 +782,10 @@ describe('PgVector', () => {
       });
 
       it('should handle nested $not with $or', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $not: { $or: [{ category: 'electronics' }, { category: 'books' }] },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $not: { $or: [{ category: 'electronics' }, { category: 'books' }] } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -701,8 +794,10 @@ describe('PgVector', () => {
       });
 
       it('should handle $not with comparison operators', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          price: { $not: { $gt: 100 } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { price: { $not: { $gt: 100 } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -711,8 +806,10 @@ describe('PgVector', () => {
       });
 
       it('should handle $not with $in operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: { $not: { $in: ['electronics', 'books'] } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: { $not: { $in: ['electronics', 'books'] } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -721,8 +818,10 @@ describe('PgVector', () => {
       });
 
       it('should handle $not with multiple nested conditions', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $not: { $and: [{ category: 'electronics' }, { price: { $gt: 50 } }] },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $not: { $and: [{ category: 'electronics' }, { price: { $gt: 50 } }] } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -731,15 +830,19 @@ describe('PgVector', () => {
       });
 
       it('should handle $not with $exists operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          tags: { $not: { $exists: true } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { tags: { $not: { $exists: true } } },
         });
         expect(results.length).toBe(0); // All test data has tags
       });
 
       it('should handle $not with array operators', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          tags: { $not: { $all: ['new', 'premium'] } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { tags: { $not: { $all: ['new', 'premium'] } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -748,16 +851,20 @@ describe('PgVector', () => {
       });
 
       it('should handle $not with complex nested conditions', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $not: {
-            $or: [
-              {
-                $and: [{ category: 'electronics' }, { price: { $gt: 90 } }],
-              },
-              {
-                $and: [{ category: 'books' }, { price: { $lt: 30 } }],
-              },
-            ],
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: {
+            $not: {
+              $or: [
+                {
+                  $and: [{ category: 'electronics' }, { price: { $gt: 90 } }],
+                },
+                {
+                  $and: [{ category: 'books' }, { price: { $lt: 30 } }],
+                },
+              ],
+            },
           },
         });
         expect(results.length).toBeGreaterThan(0);
@@ -769,18 +876,26 @@ describe('PgVector', () => {
       });
 
       it('should handle $not with empty arrays', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          tags: { $not: { $in: [] } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { tags: { $not: { $in: [] } } },
         });
         expect(results.length).toBeGreaterThan(0); // Should match all records
       });
 
       it('should handle $not with null values', async () => {
         // First insert a record with null value
-        await vectorDB.upsert(indexName, [[1, 0.1, 0]], [{ category: null, price: 0 }]);
+        await vectorDB.upsert({
+          indexName,
+          vectors: [[1, 0.1, 0]],
+          metadata: [{ category: null, price: 0 }],
+        });
 
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: { $not: { $eq: null } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: { $not: { $eq: null } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -789,8 +904,10 @@ describe('PgVector', () => {
       });
 
       it('should handle $not with boolean values', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          active: { $not: { $eq: true } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { active: { $not: { $eq: true } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -799,30 +916,42 @@ describe('PgVector', () => {
       });
 
       it('should handle $not with multiple conditions', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $not: { category: 'electronics', price: { $gt: 50 } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $not: { category: 'electronics', price: { $gt: 50 } } },
         });
         expect(results.length).toBeGreaterThan(0);
       });
 
       it('should handle $not with $not operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $not: { $not: { category: 'electronics' } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $not: { $not: { category: 'electronics' } } },
         });
         expect(results.length).toBeGreaterThan(0);
       });
 
       it('should handle $not in nested fields', async () => {
-        await vectorDB.upsert(indexName, [[1, 0.1, 0]], [{ user: { profile: { price: 10 } } }]);
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          'user.profile.price': { $not: { $gt: 25 } },
+        await vectorDB.upsert({
+          indexName,
+          vectors: [[1, 0.1, 0]],
+          metadata: [{ user: { profile: { price: 10 } } }],
+        });
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { 'user.profile.price': { $not: { $gt: 25 } } },
         });
         expect(results.length).toBe(1);
       });
 
       it('should handle $not with multiple operators', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          price: { $not: { $gte: 30, $lte: 70 } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { price: { $not: { $gte: 30, $lte: 70 } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -832,8 +961,10 @@ describe('PgVector', () => {
       });
 
       it('should handle $not with comparison operators', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          price: { $not: { $gt: 100 } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { price: { $not: { $gt: 100 } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -842,10 +973,10 @@ describe('PgVector', () => {
       });
 
       it('should handle $not with $and', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $not: {
-            $and: [{ category: 'electronics' }, { price: { $gt: 50 } }],
-          },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $not: { $and: [{ category: 'electronics' }, { price: { $gt: 50 } }] } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -854,8 +985,10 @@ describe('PgVector', () => {
       });
 
       it('should handle $nor with $or', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $nor: [{ $or: [{ category: 'electronics' }, { category: 'books' }] }, { price: { $gt: 75 } }],
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $nor: [{ $or: [{ category: 'electronics' }, { category: 'books' }] }, { price: { $gt: 75 } }] },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -865,11 +998,15 @@ describe('PgVector', () => {
       });
 
       it('should handle $nor with nested $and conditions', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $nor: [
-            { $and: [{ category: 'electronics' }, { active: true }] },
-            { $and: [{ category: 'books' }, { price: { $lt: 30 } }] },
-          ],
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: {
+            $nor: [
+              { $and: [{ category: 'electronics' }, { active: true }] },
+              { $and: [{ category: 'books' }, { price: { $lt: 30 } }] },
+            ],
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -882,8 +1019,12 @@ describe('PgVector', () => {
       });
 
       it('should handle nested $and with $or and $not', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $and: [{ $or: [{ category: 'electronics' }, { category: 'books' }] }, { $not: { price: { $lt: 50 } } }],
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: {
+            $and: [{ $or: [{ category: 'electronics' }, { category: 'books' }] }, { $not: { price: { $lt: 50 } } }],
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -893,8 +1034,10 @@ describe('PgVector', () => {
       });
 
       it('should handle $or with multiple $not conditions', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $or: [{ $not: { category: 'electronics' } }, { $not: { price: { $gt: 50 } } }],
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $or: [{ $not: { category: 'electronics' } }, { $not: { price: { $gt: 50 } } }] },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -906,29 +1049,43 @@ describe('PgVector', () => {
     // Edge Cases and Special Values
     describe('Edge Cases and Special Values', () => {
       it('should handle empty result sets with valid filters', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          price: { $gt: 1000 },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { price: { $gt: 1000 } },
         });
         expect(results).toHaveLength(0);
       });
 
       it('should throw error for invalid operator', async () => {
         await expect(
-          vectorDB.query(indexName, [1, 0, 0], 10, {
-            price: { $invalid: 100 },
+          vectorDB.query({
+            indexName,
+            queryVector: [1, 0, 0],
+            filter: { price: { $invalid: 100 } },
           }),
         ).rejects.toThrow('Unsupported operator: $invalid');
       });
 
       it('should handle empty filter object', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {});
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: {},
+        });
         expect(results.length).toBeGreaterThan(0);
       });
 
       it('should handle numeric string comparisons', async () => {
-        await vectorDB.upsert(indexName, [[1, 0.1, 0]], [{ numericString: '123' }]);
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          numericString: { $gt: '100' },
+        await vectorDB.upsert({
+          indexName,
+          vectors: [[1, 0.1, 0]],
+          metadata: [{ numericString: '123' }],
+        });
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { numericString: { $gt: '100' } },
         });
         expect(results.length).toBeGreaterThan(0);
         expect(results[0]?.metadata?.numericString).toBe('123');
@@ -938,7 +1095,12 @@ describe('PgVector', () => {
     // Score Threshold Tests
     describe('Score Threshold', () => {
       it('should respect minimum score threshold', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, { category: 'electronics' }, false, 0.9);
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: 'electronics' },
+          minScore: 0.9,
+        });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
           expect(result.score).toBeGreaterThan(0.9);
@@ -949,43 +1111,46 @@ describe('PgVector', () => {
     describe('Edge Cases and Special Values', () => {
       // Additional Edge Cases
       it('should handle empty result sets with valid filters', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          price: { $gt: 1000 },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { price: { $gt: 1000 } },
         });
         expect(results).toHaveLength(0);
       });
 
       it('should handle empty filter object', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {});
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: {},
+        });
         expect(results.length).toBeGreaterThan(0);
       });
 
       it('should handle non-existent field', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          nonexistent: {
-            $elemMatch: {
-              $eq: 'value',
-            },
-          },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { nonexistent: { $elemMatch: { $eq: 'value' } } },
         });
         expect(results).toHaveLength(0);
       });
 
       it('should handle non-existent values', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          tags: {
-            $elemMatch: {
-              $eq: 'nonexistent-tag',
-            },
-          },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { tags: { $elemMatch: { $eq: 'nonexistent-tag' } } },
         });
         expect(results).toHaveLength(0);
       });
       // Empty Conditions Tests
       it('should handle empty conditions in logical operators', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $and: [],
-          category: 'electronics',
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $and: [], category: 'electronics' },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -994,9 +1159,10 @@ describe('PgVector', () => {
       });
 
       it('should handle empty $and conditions', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $and: [],
-          category: 'electronics',
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $and: [], category: 'electronics' },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -1005,17 +1171,19 @@ describe('PgVector', () => {
       });
 
       it('should handle empty $or conditions', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $or: [],
-          category: 'electronics',
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $or: [], category: 'electronics' },
         });
         expect(results).toHaveLength(0);
       });
 
       it('should handle empty $nor conditions', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $nor: [],
-          category: 'electronics',
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $nor: [], category: 'electronics' },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -1025,29 +1193,29 @@ describe('PgVector', () => {
 
       it('should handle empty $not conditions', async () => {
         await expect(
-          vectorDB.query(indexName, [1, 0, 0], 10, {
-            $not: {},
-            category: 'electronics',
+          vectorDB.query({
+            indexName,
+            queryVector: [1, 0, 0],
+            filter: { $not: {}, category: 'electronics' },
           }),
         ).rejects.toThrow('$not operator cannot be empty');
       });
 
       it('should handle multiple empty logical operators', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $and: [],
-          $or: [],
-          $nor: [],
-          category: 'electronics',
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $and: [], $or: [], $nor: [], category: 'electronics' },
         });
         expect(results).toHaveLength(0);
       });
 
       // Nested Field Tests
       it('should handle deeply nested metadata paths', async () => {
-        await vectorDB.upsert(
+        await vectorDB.upsert({
           indexName,
-          [[1, 0.1, 0]],
-          [
+          vectors: [[1, 0.1, 0]],
+          metadata: [
             {
               level1: {
                 level2: {
@@ -1056,32 +1224,34 @@ describe('PgVector', () => {
               },
             },
           ],
-        );
+        });
 
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          'level1.level2.level3': 'deep value',
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { 'level1.level2.level3': 'deep value' },
         });
         expect(results).toHaveLength(1);
         expect(results[0]?.metadata?.level1?.level2?.level3).toBe('deep value');
       });
 
       it('should handle non-existent nested paths', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          'nonexistent.path': 'value',
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { 'nonexistent.path': 'value' },
         });
         expect(results).toHaveLength(0);
       });
 
       // Score Threshold Tests
       it('should respect minimum score threshold', async () => {
-        const results = await vectorDB.query(
-          indexName,
-          [1, 0, 0],
-          10,
-          { category: 'electronics' },
-          false,
-          0.9, // minScore
-        );
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: 'electronics' },
+          minScore: 0.9, // minScore
+        });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
           expect(result.score).toBeGreaterThan(0.9);
@@ -1090,17 +1260,21 @@ describe('PgVector', () => {
 
       // Complex Nested Operators Test
       it('should handle deeply nested logical operators', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $and: [
-            {
-              $or: [{ category: 'electronics' }, { $and: [{ category: 'books' }, { price: { $lt: 30 } }] }],
-            },
-            {
-              $not: {
-                $or: [{ active: false }, { price: { $gt: 100 } }],
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: {
+            $and: [
+              {
+                $or: [{ category: 'electronics' }, { $and: [{ category: 'books' }, { price: { $lt: 30 } }] }],
               },
-            },
-          ],
+              {
+                $not: {
+                  $or: [{ active: false }, { price: { $gt: 100 } }],
+                },
+              },
+            ],
+          },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -1118,16 +1292,19 @@ describe('PgVector', () => {
 
       it('should throw error for invalid operator', async () => {
         await expect(
-          vectorDB.query(indexName, [1, 0, 0], 10, {
-            price: { $invalid: 100 },
+          vectorDB.query({
+            indexName,
+            queryVector: [1, 0, 0],
+            filter: { price: { $invalid: 100 } },
           }),
         ).rejects.toThrow('Unsupported operator: $invalid');
       });
 
       it('should handle multiple logical operators at root level', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          $and: [{ category: 'electronics' }],
-          $or: [{ price: { $lt: 100 } }, { price: { $gt: 20 } }],
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { $and: [{ category: 'electronics' }], $or: [{ price: { $lt: 100 } }, { price: { $gt: 20 } }] },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -1138,34 +1315,63 @@ describe('PgVector', () => {
 
       it('should handle non-array field with $elemMatch', async () => {
         // First insert a record with non-array field
-        await vectorDB.upsert(indexName, [[1, 0.1, 0]], [{ tags: 'not-an-array' }]);
+        await vectorDB.upsert({
+          indexName,
+          vectors: [[1, 0.1, 0]],
+          metadata: [{ tags: 'not-an-array' }],
+        });
 
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          tags: {
-            $elemMatch: {
-              $eq: 'value',
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: {
+            tags: {
+              $elemMatch: {
+                $eq: 'value',
+              },
             },
           },
         });
         expect(results).toHaveLength(0); // Should return no results for non-array field
       });
       it('should handle undefined filter', async () => {
-        const results1 = await vectorDB.query(indexName, [1, 0, 0], 10, undefined);
-        const results2 = await vectorDB.query(indexName, [1, 0, 0], 10);
+        const results1 = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: undefined,
+        });
+        const results2 = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+        });
         expect(results1).toEqual(results2);
         expect(results1.length).toBeGreaterThan(0);
       });
 
       it('should handle empty object filter', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {});
-        const results2 = await vectorDB.query(indexName, [1, 0, 0], 10);
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: {},
+        });
+        const results2 = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+        });
         expect(results).toEqual(results2);
         expect(results.length).toBeGreaterThan(0);
       });
 
       it('should handle null filter', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, null as any);
-        const results2 = await vectorDB.query(indexName, [1, 0, 0], 10);
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: null,
+        });
+        const results2 = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+        });
         expect(results).toEqual(results2);
         expect(results.length).toBeGreaterThan(0);
       });
@@ -1174,58 +1380,82 @@ describe('PgVector', () => {
     // Regex Operator Tests
     describe('Regex Operators', () => {
       it('should handle $regex with case sensitivity', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: { $regex: 'ELECTRONICS' },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: { $regex: 'ELECTRONICS' } },
         });
         expect(results).toHaveLength(0);
       });
 
       it('should handle $regex with case insensitivity', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: { $regex: 'ELECTRONICS', $options: 'i' },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: { $regex: 'ELECTRONICS', $options: 'i' } },
         });
         expect(results).toHaveLength(2);
       });
 
       it('should handle $regex with start anchor', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: { $regex: '^elect' },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: { $regex: '^elect' } },
         });
         expect(results).toHaveLength(2);
       });
 
       it('should handle $regex with end anchor', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: { $regex: 'nics$' },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: { $regex: 'nics$' } },
         });
         expect(results).toHaveLength(2);
       });
 
       it('should handle multiline flag', async () => {
-        await vectorDB.upsert(indexName, [[1, 0.1, 0]], [{ description: 'First line\nSecond line\nThird line' }]);
+        await vectorDB.upsert({
+          indexName,
+          vectors: [[1, 0.1, 0]],
+          metadata: [{ description: 'First line\nSecond line\nThird line' }],
+        });
 
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          description: { $regex: '^Second', $options: 'm' },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { description: { $regex: '^Second', $options: 'm' } },
         });
         expect(results).toHaveLength(1);
       });
 
       it('should handle dotall flag', async () => {
-        await vectorDB.upsert(indexName, [[1, 0.1, 0]], [{ description: 'First\nSecond\nThird' }]);
+        await vectorDB.upsert({
+          indexName,
+          vectors: [[1, 0.1, 0]],
+          metadata: [{ description: 'First\nSecond\nThird' }],
+        });
 
-        const withoutS = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          description: { $regex: 'First[^\\n]*Third' },
+        const withoutS = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { description: { $regex: 'First[^\\n]*Third' } },
         });
         expect(withoutS).toHaveLength(0);
 
-        const withS = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          description: { $regex: 'First.*Third', $options: 's' },
+        const withS = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { description: { $regex: 'First.*Third', $options: 's' } },
         });
         expect(withS).toHaveLength(1);
       });
       it('should handle $not with $regex operator', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 10, {
-          category: { $not: { $regex: '^elect' } },
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          filter: { category: { $not: { $regex: '^elect' } } },
         });
         expect(results.length).toBeGreaterThan(0);
         results.forEach(result => {
@@ -1245,11 +1475,19 @@ describe('PgVector', () => {
 
     describe('HNSW Parameters', () => {
       beforeAll(async () => {
-        await vectorDB.createIndex(indexName, 3, 'cosine', {
-          type: 'hnsw',
-          hnsw: { m: 16, efConstruction: 64 },
+        await vectorDB.createIndex({
+          indexName,
+          dimension: 3,
+          metric: 'cosine',
+          indexConfig: {
+            type: 'hnsw',
+            hnsw: { m: 16, efConstruction: 64 },
+          },
+        });
+        await vectorDB.upsert({
+          indexName,
+          vectors,
         });
-        await vectorDB.upsert(indexName, vectors);
       });
 
       afterAll(async () => {
@@ -1257,14 +1495,23 @@ describe('PgVector', () => {
       });
 
       it('should use default ef value', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 2);
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          topK: 2,
+        });
         expect(results).toHaveLength(2);
         expect(results[0]?.score).toBeCloseTo(1, 5);
         expect(results[1]?.score).toBeGreaterThan(0.9); // Second vector should be close
       });
 
       it('should respect custom ef value', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 2, undefined, undefined, undefined, { ef: 100 });
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          topK: 2,
+          ef: 100,
+        });
         expect(results).toHaveLength(2);
         expect(results[0]?.score).toBeCloseTo(1, 5);
         expect(results[1]?.score).toBeGreaterThan(0.9);
@@ -1273,11 +1520,19 @@ describe('PgVector', () => {
 
     describe('IVF Parameters', () => {
       beforeAll(async () => {
-        await vectorDB.createIndex(indexName, 3, 'cosine', {
-          type: 'ivfflat',
-          ivf: { lists: 2 }, // Small number for test data
+        await vectorDB.createIndex({
+          indexName,
+          dimension: 3,
+          metric: 'cosine',
+          indexConfig: {
+            type: 'ivfflat',
+            ivf: { lists: 2 }, // Small number for test data
+          },
+        });
+        await vectorDB.upsert({
+          indexName,
+          vectors,
         });
-        await vectorDB.upsert(indexName, vectors);
       });
 
       afterAll(async () => {
@@ -1285,18 +1540,145 @@ describe('PgVector', () => {
       });
 
       it('should use default probe value', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 2);
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          topK: 2,
+        });
         expect(results).toHaveLength(2);
         expect(results[0]?.score).toBeCloseTo(1, 5);
         expect(results[1]?.score).toBeGreaterThan(0.9);
       });
 
       it('should respect custom probe value', async () => {
-        const results = await vectorDB.query(indexName, [1, 0, 0], 2, undefined, undefined, undefined, { probes: 2 });
+        const results = await vectorDB.query({
+          indexName,
+          queryVector: [1, 0, 0],
+          topK: 2,
+          probes: 2,
+        });
         expect(results).toHaveLength(2);
         expect(results[0]?.score).toBeCloseTo(1, 5);
         expect(results[1]?.score).toBeGreaterThan(0.9);
       });
     });
   });
+  describe('Deprecation Warnings', () => {
+    const indexName = 'testdeprecationwarnings';
+
+    const indexName2 = 'testdeprecationwarnings2';
+
+    let warnSpy;
+
+    beforeAll(async () => {
+      await vectorDB.createIndex({ indexName: indexName, dimension: 3 });
+    });
+
+    afterAll(async () => {
+      await vectorDB.deleteIndex(indexName);
+      await vectorDB.deleteIndex(indexName2);
+    });
+
+    beforeEach(async () => {
+      warnSpy = vi.spyOn(vectorDB['logger'], 'warn');
+    });
+
+    afterEach(async () => {
+      warnSpy.mockRestore();
+      await vectorDB.deleteIndex(indexName2);
+    });
+
+    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 show deprecation warning when using individual args for buildIndex', async () => {
+      await vectorDB.buildIndex(indexName, 'cosine', { type: 'flat' });
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Deprecation Warning: Passing individual arguments to buildIndex() is deprecated'),
+      );
+    });
+
+    it('should not show deprecation warning when using object param for buildIndex', async () => {
+      await vectorDB.buildIndex({
+        indexName: indexName,
+        metric: 'cosine',
+        indexConfig: { type: 'flat' },
+      });
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    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);
+
+      // BuildIndex
+      await expect(vectorDB.buildIndex(indexName, 'cosine', { type: 'flat' })).resolves.not.toThrow();
+    });
+  });
 });