@mastra/vectorize 0.1.6-alpha.1 → 0.1.6-alpha.3

package/.turbo/turbo-build.log

@@ -1,18 +1,23 @@
 
-> @mastra/vectorize@0.1.6-alpha.1 build /home/runner/work/mastra/mastra/stores/vectorize
-> tsup src/index.ts --format esm --experimental-dts --clean --treeshake
+> @mastra/vectorize@0.1.6-alpha.3 build /home/runner/work/mastra/mastra/stores/vectorize
+> tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
 CLI tsup v8.3.6
 TSC Build start
-TSC ⚡️ Build success in 13586ms
+TSC ⚡️ Build success in 12974ms
 DTS Build start
 CLI Target: es2022
 Analysis will use the bundled TypeScript version 5.7.3
 Writing package typings: /home/runner/work/mastra/mastra/stores/vectorize/dist/_tsup-dts-rollup.d.ts
-DTS ⚡️ Build success in 10111ms
+Analysis will use the bundled TypeScript version 5.7.3
+Writing package typings: /home/runner/work/mastra/mastra/stores/vectorize/dist/_tsup-dts-rollup.d.cts
+DTS ⚡️ Build success in 17317ms
 CLI Cleaning output folder
 ESM Build start
-ESM dist/index.js 5.26 KB
-ESM ⚡️ Build success in 497ms
+CJS Build start
+CJS dist/index.cjs 5.68 KB
+CJS ⚡️ Build success in 465ms
+ESM dist/index.js 5.48 KB
+ESM ⚡️ Build success in 465ms

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @mastra/vectorize
 
+## 0.1.6-alpha.3
+
+### Patch Changes
+
+- 0fd78ac: Update vector store functions to use object params
+- fd14a3f: Updating filter location from @mastra/core/filter to @mastra/core/vector/filter
+- c4fdac3: Updated tests for upstash and astra
+- 4d4e1e1: Updated vector tests and pinecone
+- bb4f447: Add support for commonjs
+- Updated dependencies [0fd78ac]
+- Updated dependencies [0d25b75]
+- Updated dependencies [fd14a3f]
+- Updated dependencies [3f369a2]
+- Updated dependencies [4d4e1e1]
+- Updated dependencies [bb4f447]
+  - @mastra/core@0.4.3-alpha.3
+
+## 0.1.6-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [2512a93]
+- Updated dependencies [e62de74]
+  - @mastra/core@0.4.3-alpha.2
+
 ## 0.1.6-alpha.1
 
 ### Patch Changes

package/README.md

@@ -14,7 +14,33 @@ npm install @mastra/vectorize
 import { VectorizeStore } from '@mastra/vectorize';
 
 const vectorStore = new VectorizeStore({
-  // configuration options
+  apiKey: process.env.VECTORIZE_API_KEY,
+  projectId: process.env.VECTORIZE_PROJECT_ID
+});
+
+// Create a new index
+await vectorStore.createIndex({
+  indexName: 'my-index',
+  dimension: 1536,
+  metric: 'cosine'
+});
+
+// Add vectors
+const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
+const metadata = [{ text: 'doc1' }, { text: 'doc2' }];
+const ids = await vectorStore.upsert({
+  indexName: 'my-index',
+  vectors,
+  metadata
+});
+
+// Query vectors
+const results = await vectorStore.query({
+  indexName: 'my-index',
+  queryVector: [0.1, 0.2, ...],
+  topK: 10,
+  filter: { text: { $eq: 'doc1' } },
+  includeVector: false
 });
 ```
 
@@ -34,6 +60,15 @@ The Vectorize vector store requires the following configuration:
 - Scalable architecture
 - Real-time updates and queries
 
+## Methods
+
+- `createIndex({ indexName, dimension, metric? })`: Create a new index
+- `upsert({ indexName, vectors, metadata?, ids? })`: Add or update vectors
+- `query({ indexName, queryVector, topK?, filter?, includeVector? })`: Search for similar vectors
+- `listIndexes()`: List all indexes
+- `describeIndex(indexName)`: Get index statistics
+- `deleteIndex(indexName)`: Delete an index
+
 ## Related Links
 
 - [Vectorize Documentation](https://www.vectorize.com/docs)

package/dist/_tsup-dts-rollup.d.cts

@@ -0,0 +1,43 @@
+import { BaseFilterTranslator } from '@mastra/core/vector/filter';
+import Cloudflare from 'cloudflare';
+import type { CreateIndexParams } from '@mastra/core/vector';
+import { MastraVector } from '@mastra/core/vector';
+import type { OperatorSupport } from '@mastra/core/vector/filter';
+import type { ParamsToArgs } from '@mastra/core/vector';
+import type { QueryResult } from '@mastra/core/vector';
+import type { QueryVectorParams } from '@mastra/core/vector';
+import type { UpsertVectorParams } from '@mastra/core/vector';
+import type { VectorFilter } from '@mastra/core/vector/filter';
+
+declare class CloudflareVector extends MastraVector {
+    client: Cloudflare;
+    accountId: string;
+    constructor({ accountId, apiToken }: {
+        accountId: string;
+        apiToken: string;
+    });
+    upsert(...args: ParamsToArgs<UpsertVectorParams>): Promise<string[]>;
+    transformFilter(filter?: VectorFilter): VectorFilter;
+    createIndex(...args: ParamsToArgs<CreateIndexParams>): Promise<void>;
+    query(...args: ParamsToArgs<QueryVectorParams>): Promise<QueryResult[]>;
+    listIndexes(): Promise<string[]>;
+    describeIndex(indexName: string): Promise<{
+        dimension: number;
+        count: number;
+        metric: "cosine" | "euclidean" | "dotproduct";
+    }>;
+    deleteIndex(indexName: string): Promise<void>;
+    createMetadataIndex(indexName: string, propertyName: string, indexType: 'string' | 'number' | 'boolean'): Promise<void>;
+    deleteMetadataIndex(indexName: string, propertyName: string): Promise<void>;
+    listMetadataIndexes(indexName: string): Promise<Cloudflare.Vectorize.Indexes.MetadataIndex.MetadataIndexListResponse.MetadataIndex[]>;
+}
+export { CloudflareVector }
+export { CloudflareVector as CloudflareVector_alias_1 }
+
+export declare class VectorizeFilterTranslator extends BaseFilterTranslator {
+    protected getSupportedOperators(): OperatorSupport;
+    translate(filter?: VectorFilter): VectorFilter;
+    private translateNode;
+}
+
+export { }

package/dist/_tsup-dts-rollup.d.ts

@@ -1,9 +1,13 @@
-import { BaseFilterTranslator } from '@mastra/core/filter';
+import { BaseFilterTranslator } from '@mastra/core/vector/filter';
 import Cloudflare from 'cloudflare';
-import type { Filter } from '@mastra/core/filter';
+import type { CreateIndexParams } from '@mastra/core/vector';
 import { MastraVector } from '@mastra/core/vector';
-import type { OperatorSupport } from '@mastra/core/filter';
+import type { OperatorSupport } from '@mastra/core/vector/filter';
+import type { ParamsToArgs } from '@mastra/core/vector';
 import type { QueryResult } from '@mastra/core/vector';
+import type { QueryVectorParams } from '@mastra/core/vector';
+import type { UpsertVectorParams } from '@mastra/core/vector';
+import type { VectorFilter } from '@mastra/core/vector/filter';
 
 declare class CloudflareVector extends MastraVector {
     client: Cloudflare;
@@ -12,10 +16,10 @@ declare class CloudflareVector extends MastraVector {
         accountId: string;
         apiToken: string;
     });
-    upsert(indexName: string, vectors: number[][], metadata?: Record<string, any>[], ids?: string[]): Promise<string[]>;
-    transformFilter(filter?: Filter): Filter | undefined;
-    createIndex(indexName: string, dimension: number, metric?: 'cosine' | 'euclidean' | 'dotproduct'): Promise<void>;
-    query(indexName: string, queryVector: number[], topK?: number, filter?: Filter, includeVector?: boolean): Promise<QueryResult[]>;
+    upsert(...args: ParamsToArgs<UpsertVectorParams>): Promise<string[]>;
+    transformFilter(filter?: VectorFilter): VectorFilter;
+    createIndex(...args: ParamsToArgs<CreateIndexParams>): Promise<void>;
+    query(...args: ParamsToArgs<QueryVectorParams>): Promise<QueryResult[]>;
     listIndexes(): Promise<string[]>;
     describeIndex(indexName: string): Promise<{
         dimension: number;
@@ -32,7 +36,7 @@ export { CloudflareVector as CloudflareVector_alias_1 }
 
 export declare class VectorizeFilterTranslator extends BaseFilterTranslator {
     protected getSupportedOperators(): OperatorSupport;
-    translate(filter?: Filter): Filter | undefined;
+    translate(filter?: VectorFilter): VectorFilter;
     private translateNode;
 }
 

package/dist/index.cjs

@@ -0,0 +1,184 @@
+'use strict';
+
+var vector = require('@mastra/core/vector');
+var Cloudflare = require('cloudflare');
+var filter = require('@mastra/core/vector/filter');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var Cloudflare__default = /*#__PURE__*/_interopDefault(Cloudflare);
+
+// src/vector/index.ts
+var VectorizeFilterTranslator = class extends filter.BaseFilterTranslator {
+  getSupportedOperators() {
+    return {
+      ...filter.BaseFilterTranslator.DEFAULT_OPERATORS,
+      logical: [],
+      array: ["$in", "$nin"],
+      element: [],
+      regex: [],
+      custom: []
+    };
+  }
+  translate(filter) {
+    if (this.isEmpty(filter)) return filter;
+    this.validateFilter(filter);
+    return this.translateNode(filter);
+  }
+  translateNode(node, currentPath = "") {
+    if (this.isRegex(node)) {
+      throw new Error("Regex is not supported in Vectorize");
+    }
+    if (this.isPrimitive(node)) return { $eq: this.normalizeComparisonValue(node) };
+    if (Array.isArray(node)) return { $in: this.normalizeArrayValues(node) };
+    const entries = Object.entries(node);
+    const firstEntry = entries[0];
+    if (entries.length === 1 && firstEntry && this.isOperator(firstEntry[0])) {
+      const [operator, value] = firstEntry;
+      return { [operator]: this.normalizeComparisonValue(value) };
+    }
+    const result = {};
+    for (const [key, value] of entries) {
+      const newPath = currentPath ? `${currentPath}.${key}` : key;
+      if (this.isOperator(key)) {
+        result[key] = this.normalizeComparisonValue(value);
+        continue;
+      }
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        if (Object.keys(value).length === 0) {
+          result[newPath] = this.translateNode(value);
+          continue;
+        }
+        const hasOperators = Object.keys(value).some((k) => this.isOperator(k));
+        if (hasOperators) {
+          result[newPath] = this.translateNode(value);
+        } else {
+          Object.assign(result, this.translateNode(value, newPath));
+        }
+      } else {
+        result[newPath] = this.translateNode(value);
+      }
+    }
+    return result;
+  }
+};
+
+// src/vector/index.ts
+var CloudflareVector = class extends vector.MastraVector {
+  client;
+  accountId;
+  constructor({ accountId, apiToken }) {
+    super();
+    this.accountId = accountId;
+    this.client = new Cloudflare__default.default({
+      apiKey: apiToken
+    });
+  }
+  async upsert(...args) {
+    const params = this.normalizeArgs("upsert", args);
+    const { indexName, vectors, metadata, ids } = params;
+    const generatedIds = ids || vectors.map(() => crypto.randomUUID());
+    const ndjson = vectors.map(
+      (vector, index) => JSON.stringify({
+        id: generatedIds[index],
+        values: vector,
+        metadata: metadata?.[index]
+      })
+    ).join("\n");
+    await this.client.vectorize.indexes.upsert(
+      indexName,
+      {
+        account_id: this.accountId,
+        body: ndjson
+      },
+      {
+        __binaryRequest: true
+      }
+    );
+    return generatedIds;
+  }
+  transformFilter(filter) {
+    const translator = new VectorizeFilterTranslator();
+    return translator.translate(filter);
+  }
+  async createIndex(...args) {
+    const params = this.normalizeArgs("createIndex", args);
+    const { indexName, dimension, metric = "cosine" } = params;
+    await this.client.vectorize.indexes.create({
+      account_id: this.accountId,
+      config: {
+        dimensions: dimension,
+        metric: metric === "dotproduct" ? "dot-product" : metric
+      },
+      name: indexName
+    });
+  }
+  async query(...args) {
+    const params = this.normalizeArgs("query", args);
+    const { indexName, queryVector, topK = 10, filter, includeVector = false } = params;
+    const translatedFilter = this.transformFilter(filter) ?? {};
+    const response = await this.client.vectorize.indexes.query(indexName, {
+      account_id: this.accountId,
+      vector: queryVector,
+      returnValues: includeVector,
+      returnMetadata: "all",
+      topK,
+      filter: translatedFilter
+    });
+    return response?.matches?.map((match) => {
+      return {
+        id: match.id,
+        metadata: match.metadata,
+        score: match.score,
+        vector: match.values
+      };
+    }) || [];
+  }
+  async listIndexes() {
+    const res = await this.client.vectorize.indexes.list({
+      account_id: this.accountId
+    });
+    return res?.result?.map((index) => index.name) || [];
+  }
+  async describeIndex(indexName) {
+    const index = await this.client.vectorize.indexes.get(indexName, {
+      account_id: this.accountId
+    });
+    const described = await this.client.vectorize.indexes.info(indexName, {
+      account_id: this.accountId
+    });
+    return {
+      dimension: described?.dimensions,
+      // Since vector_count is not available in the response,
+      // we might need a separate API call to get the count if needed
+      count: described?.vectorCount || 0,
+      metric: index?.config?.metric
+    };
+  }
+  async deleteIndex(indexName) {
+    await this.client.vectorize.indexes.delete(indexName, {
+      account_id: this.accountId
+    });
+  }
+  async createMetadataIndex(indexName, propertyName, indexType) {
+    await this.client.vectorize.indexes.metadataIndex.create(indexName, {
+      account_id: this.accountId,
+      propertyName,
+      indexType
+    });
+  }
+  async deleteMetadataIndex(indexName, propertyName) {
+    await this.client.vectorize.indexes.metadataIndex.delete(indexName, {
+      account_id: this.accountId,
+      propertyName
+    });
+  }
+  async listMetadataIndexes(indexName) {
+    const res = await this.client.vectorize.indexes.metadataIndex.list(indexName, {
+      account_id: this.accountId
+    });
+    return res?.metadataIndexes ?? [];
+  }
+};
+
+exports.CloudflareVector = CloudflareVector;

package/dist/index.d.cts

@@ -0,0 +1 @@
+export { CloudflareVector } from './_tsup-dts-rollup.cjs';

package/dist/index.js

@@ -1,6 +1,6 @@
 import { MastraVector } from '@mastra/core/vector';
 import Cloudflare from 'cloudflare';
-import { BaseFilterTranslator } from '@mastra/core/filter';
+import { BaseFilterTranslator } from '@mastra/core/vector/filter';
 
 // src/vector/index.ts
 var VectorizeFilterTranslator = class extends BaseFilterTranslator {
@@ -68,7 +68,9 @@ var CloudflareVector = class extends MastraVector {
       apiKey: apiToken
     });
   }
-  async upsert(indexName, vectors, metadata, ids) {
+  async upsert(...args) {
+    const params = this.normalizeArgs("upsert", args);
+    const { indexName, vectors, metadata, ids } = params;
     const generatedIds = ids || vectors.map(() => crypto.randomUUID());
     const ndjson = vectors.map(
       (vector, index) => JSON.stringify({
@@ -91,10 +93,11 @@ var CloudflareVector = class extends MastraVector {
   }
   transformFilter(filter) {
     const translator = new VectorizeFilterTranslator();
-    const translatedFilter = translator.translate(filter);
-    return translatedFilter;
+    return translator.translate(filter);
   }
-  async createIndex(indexName, dimension, metric = "cosine") {
+  async createIndex(...args) {
+    const params = this.normalizeArgs("createIndex", args);
+    const { indexName, dimension, metric = "cosine" } = params;
     await this.client.vectorize.indexes.create({
       account_id: this.accountId,
       config: {
@@ -104,8 +107,10 @@ var CloudflareVector = class extends MastraVector {
       name: indexName
     });
   }
-  async query(indexName, queryVector, topK = 10, filter, includeVector = false) {
-    const translatedFilter = this.transformFilter(filter);
+  async query(...args) {
+    const params = this.normalizeArgs("query", args);
+    const { indexName, queryVector, topK = 10, filter, includeVector = false } = params;
+    const translatedFilter = this.transformFilter(filter) ?? {};
     const response = await this.client.vectorize.indexes.query(indexName, {
       account_id: this.accountId,
       vector: queryVector,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/vectorize",
-  "version": "0.1.6-alpha.1",
+  "version": "0.1.6-alpha.3",
   "description": "Cloudflare Vectorize store provider for Mastra",
   "type": "module",
   "main": "dist/index.js",
@@ -10,13 +10,17 @@
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
       }
     },
     "./package.json": "./package.json"
   },
   "dependencies": {
     "cloudflare": "^4.0.0",
-    "@mastra/core": "^0.4.3-alpha.1"
+    "@mastra/core": "^0.4.3-alpha.3"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.49.2",
@@ -28,7 +32,7 @@
     "@internal/lint": "0.0.0"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --experimental-dts --clean --treeshake",
+    "build": "tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake",
     "build:watch": "pnpm build --watch",
     "test": "vitest run",
     "lint": "eslint ."

package/src/vector/filter.ts

@@ -1,5 +1,5 @@
-import { BaseFilterTranslator } from '@mastra/core/filter';
-import type { Filter, FieldCondition, OperatorSupport } from '@mastra/core/filter';
+import { BaseFilterTranslator } from '@mastra/core/vector/filter';
+import type { VectorFilter, FieldCondition, OperatorSupport } from '@mastra/core/vector/filter';
 
 export class VectorizeFilterTranslator extends BaseFilterTranslator {
   protected override getSupportedOperators(): OperatorSupport {
@@ -13,13 +13,13 @@ export class VectorizeFilterTranslator extends BaseFilterTranslator {
     };
   }
 
-  translate(filter?: Filter): Filter | undefined {
+  translate(filter?: VectorFilter): VectorFilter {
     if (this.isEmpty(filter)) return filter;
-    this.validateFilter(filter as Filter);
+    this.validateFilter(filter);
     return this.translateNode(filter);
   }
 
-  private translateNode(node: Filter | FieldCondition, currentPath: string = ''): any {
+  private translateNode(node: VectorFilter | FieldCondition, currentPath: string = ''): any {
     if (this.isRegex(node)) {
       throw new Error('Regex is not supported in Vectorize');
     }

package/src/vector/index.test.ts

@@ -1,8 +1,10 @@
 import { randomUUID } from 'crypto';
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll, beforeEach, vi, afterEach } from 'vitest';
 
 import { CloudflareVector } from './';
 
+vi.setConfig({ testTimeout: 80_000, hookTimeout: 80_000 });
+
 function waitUntilReady(vector: CloudflareVector, indexName: string) {
   return new Promise(resolve => {
     const interval = setInterval(async () => {
@@ -106,7 +108,7 @@ describe('CloudflareVector', () => {
     const tempIndexName = 'test_temp_index';
 
     it('should create and list indexes', async () => {
-      await vectorDB.createIndex(tempIndexName, VECTOR_DIMENSION, 'cosine');
+      await vectorDB.createIndex({ indexName: tempIndexName, dimension: VECTOR_DIMENSION, metric: 'cosine' });
       await waitUntilReady(vectorDB, tempIndexName);
       const indexes = await vectorDB.listIndexes();
       expect(indexes).toContain(tempIndexName);
@@ -131,7 +133,7 @@ describe('CloudflareVector', () => {
   describe('Vector Operations', () => {
     let vectorIds: string[];
     it('should create index before operations', async () => {
-      await vectorDB.createIndex(testIndexName, VECTOR_DIMENSION, 'cosine');
+      await vectorDB.createIndex({ indexName: testIndexName, dimension: VECTOR_DIMENSION, metric: 'cosine' });
       await waitUntilReady(vectorDB, testIndexName);
       const indexes = await vectorDB.listIndexes();
       expect(indexes).toContain(testIndexName);
@@ -142,14 +144,14 @@ describe('CloudflareVector', () => {
 
       const testMetadata = [{ label: 'first-dimension' }, { label: 'second-dimension' }, { label: 'third-dimension' }];
 
-      vectorIds = await vectorDB.upsert(testIndexName, testVectors, testMetadata);
+      vectorIds = await vectorDB.upsert({ indexName: testIndexName, vectors: testVectors, metadata: testMetadata });
       expect(vectorIds).toHaveLength(3);
 
       await waitUntilVectorsIndexed(vectorDB, testIndexName, 3);
       const stats = await vectorDB.describeIndex(testIndexName);
       expect(stats.count).toBeGreaterThan(0);
 
-      const results = await vectorDB.query(testIndexName, createVector(0, 0.9), 3);
+      const results = await vectorDB.query({ indexName: testIndexName, queryVector: createVector(0, 0.9), topK: 3 });
       expect(results).toHaveLength(3);
 
       if (results.length > 0) {
@@ -158,7 +160,12 @@ describe('CloudflareVector', () => {
     }, 30000);
 
     it('should query vectors and return vector in results', async () => {
-      const results = await vectorDB.query(testIndexName, createVector(0, 0.9), 3, undefined, true);
+      const results = await vectorDB.query({
+        indexName: testIndexName,
+        queryVector: createVector(0, 0.9),
+        topK: 3,
+        includeVector: true,
+      });
 
       expect(results).toHaveLength(3);
 
@@ -171,23 +178,27 @@ describe('CloudflareVector', () => {
 
   describe('Error Handling', () => {
     it('should handle invalid dimension vectors', async () => {
-      await expect(vectorDB.upsert(testIndexName, [[1.0, 0.0]])).rejects.toThrow();
+      await expect(vectorDB.upsert({ indexName: testIndexName, vectors: [[1.0, 0.0]] })).rejects.toThrow();
     });
 
     it('should handle querying with wrong dimensions', async () => {
-      await expect(vectorDB.query(testIndexName, [1.0, 0.0])).rejects.toThrow();
+      await expect(vectorDB.query({ indexName: testIndexName, queryVector: [1.0, 0.0] })).rejects.toThrow();
     });
 
     it('should handle non-existent index operations', async () => {
       const nonExistentIndex = 'non_existent_index';
-      await expect(vectorDB.query(nonExistentIndex, createVector(0, 1.0))).rejects.toThrow();
+      await expect(
+        vectorDB.query({ indexName: nonExistentIndex, queryVector: createVector(0, 1.0) }),
+      ).rejects.toThrow();
     });
 
     it('rejects queries with filter keys longer than 512 characters', async () => {
       const longKey = 'a'.repeat(513);
       const filter = { [longKey]: 'value' };
 
-      await expect(vectorDB.query(testIndexName, createVector(0, 0.9), 10, filter)).rejects.toThrow();
+      await expect(
+        vectorDB.query({ indexName: testIndexName, queryVector: createVector(0, 0.9), topK: 10, filter }),
+      ).rejects.toThrow();
     });
 
     it('rejects queries with filter keys containing invalid characters', async () => {
@@ -198,7 +209,9 @@ describe('CloudflareVector', () => {
       ];
 
       for (const filter of invalidFilters) {
-        await expect(vectorDB.query(testIndexName, createVector(0, 0.9), 10, filter)).rejects.toThrow();
+        await expect(
+          vectorDB.query({ indexName: testIndexName, queryVector: createVector(0, 0.9), topK: 10, filter }),
+        ).rejects.toThrow();
       }
     });
 
@@ -210,13 +223,17 @@ describe('CloudflareVector', () => {
       ];
 
       for (const filter of validFilters) {
-        await expect(vectorDB.query(testIndexName, createVector(0, 0.9), 10, filter)).resolves.not.toThrow();
+        await expect(
+          vectorDB.query({ indexName: testIndexName, queryVector: createVector(0, 0.9), topK: 10, filter }),
+        ).resolves.not.toThrow();
       }
     });
 
     it('rejects queries with empty object field values', async () => {
       const emptyFilters = { field: {} };
-      await expect(vectorDB.query(testIndexName, createVector(0, 0.9), 10, emptyFilters)).rejects.toThrow();
+      await expect(
+        vectorDB.query({ indexName: testIndexName, queryVector: createVector(0, 0.9), topK: 10, filter: emptyFilters }),
+      ).rejects.toThrow();
     });
 
     it('rejects oversized filter queries', async () => {
@@ -225,19 +242,27 @@ describe('CloudflareVector', () => {
         field2: { $in: Array(1000).fill(123) },
       };
 
-      await expect(vectorDB.query(testIndexName, createVector(0, 0.9), 10, largeFilter)).rejects.toThrow();
+      await expect(
+        vectorDB.query({ indexName: testIndexName, queryVector: createVector(0, 0.9), topK: 10, filter: largeFilter }),
+      ).rejects.toThrow();
     });
 
     it('rejects queries with array values in comparison operators', async () => {
       await expect(
-        vectorDB.query(testIndexName, createVector(0, 0.9), 10, {
-          field: { $gt: [] },
+        vectorDB.query({
+          indexName: testIndexName,
+          queryVector: createVector(0, 0.9),
+          topK: 10,
+          filter: { field: { $gt: [] } },
         }),
       ).rejects.toThrow();
 
       await expect(
-        vectorDB.query(testIndexName, createVector(0, 0.9), 10, {
-          field: { $lt: [1, 2, 3] },
+        vectorDB.query({
+          indexName: testIndexName,
+          queryVector: createVector(0, 0.9),
+          topK: 10,
+          filter: { field: { $lt: [1, 2, 3] } },
         }),
       ).rejects.toThrow();
     });
@@ -245,7 +270,7 @@ describe('CloudflareVector', () => {
 
   describe('Metadata Filter Tests', () => {
     beforeAll(async () => {
-      await vectorDB.createIndex(testIndexName2, VECTOR_DIMENSION, 'cosine');
+      await vectorDB.createIndex({ indexName: testIndexName2, dimension: VECTOR_DIMENSION, metric: 'cosine' });
       await waitUntilReady(vectorDB, testIndexName2);
 
       await vectorDB.createMetadataIndex(testIndexName2, 'price', 'number');
@@ -327,12 +352,12 @@ describe('CloudflareVector', () => {
         },
       ];
 
-      await vectorDB.upsert(testIndexName2, vectors, metadata);
+      await vectorDB.upsert({ indexName: testIndexName2, vectors, metadata });
       await waitUntilVectorsIndexed(vectorDB, testIndexName2, vectors.length);
 
       const stats = await vectorDB.describeIndex(testIndexName2);
       expect(stats.count).toBe(vectors.length);
-    }, 300000);
+    }, 800000);
 
     afterAll(async () => {
       const currentMetadata = await vectorDB.listMetadataIndexes(testIndexName2);
@@ -340,12 +365,14 @@ describe('CloudflareVector', () => {
         await vectorDB.deleteMetadataIndex(testIndexName2, propertyName as string);
       }
       await vectorDB.deleteIndex(testIndexName2);
-    }, 300000);
+    }, 800000);
 
     describe('Basic Equality Operators', () => {
       it('filters with $eq operator', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          category: 'electronics',
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { category: 'electronics' },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -354,8 +381,10 @@ describe('CloudflareVector', () => {
       });
 
       it('filters with $ne operator', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          category: { $ne: 'electronics' },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { category: { $ne: 'electronics' } },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -366,8 +395,10 @@ describe('CloudflareVector', () => {
 
     describe('Numeric Comparison Operators', () => {
       it('filters with $gt operator', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          price: { $gt: 150 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { price: { $gt: 150 } },
         });
         expect(results.length).toBe(1);
         results.forEach(result => {
@@ -376,8 +407,10 @@ describe('CloudflareVector', () => {
       });
 
       it('filters with $gte operator', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          price: { $gte: 100 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { price: { $gte: 100 } },
         });
         expect(results.length).toBe(3);
         results.forEach(result => {
@@ -387,8 +420,10 @@ describe('CloudflareVector', () => {
       });
 
       it('filters with $lt operator', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          price: { $lt: 150 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { price: { $lt: 150 } },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -398,8 +433,10 @@ describe('CloudflareVector', () => {
       });
 
       it('filters with $lte operator', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          price: { $lte: 150 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { price: { $lte: 150 } },
         });
         expect(results.length).toBe(3);
         results.forEach(result => {
@@ -411,8 +448,10 @@ describe('CloudflareVector', () => {
 
     describe('Array Operators', () => {
       it('filters with $in operator for exact matches', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          category: { $in: ['electronics'] },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { category: { $in: ['electronics'] } },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -421,8 +460,10 @@ describe('CloudflareVector', () => {
       });
 
       it('filters with $nin operator', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          category: { $nin: ['electronics'] },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { category: { $nin: ['electronics'] } },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -433,16 +474,20 @@ describe('CloudflareVector', () => {
 
     describe('Boolean Operations', () => {
       it('filters with boolean values', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          isActive: true,
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { isActive: true },
         });
         expect(results.length).toBe(1);
         expect(results[0]?.metadata?.isActive).toBe(true);
       }, 5000);
 
       it('filters with $ne on boolean values', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          isActive: { $ne: true },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { isActive: { $ne: true } },
         });
         expect(results.length).toBe(3);
         results.forEach(result => {
@@ -453,8 +498,10 @@ describe('CloudflareVector', () => {
 
     describe('Nested Field Operations', () => {
       it('filters on nested fields with comparison operators', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          'nested.number': { $gt: 100 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { 'nested.number': { $gt: 100 } },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -463,9 +510,10 @@ describe('CloudflareVector', () => {
       });
 
       it('combines nested field filters with top-level filters', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          'nested.number': { $lt: 200 },
-          category: 'electronics',
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { 'nested.number': { $lt: 200 }, category: 'electronics' },
         });
         expect(results.length).toBe(1);
         expect(results[0]?.metadata?.nested?.number).toBeLessThan(200);
@@ -473,8 +521,10 @@ describe('CloudflareVector', () => {
       });
 
       it('handles nested string equality', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          'nested.string': 'premium',
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { 'nested.string': 'premium' },
         });
         expect(results.length).toBe(3);
         results.forEach(result => {
@@ -483,9 +533,10 @@ describe('CloudflareVector', () => {
       }, 10000);
 
       it('combines nested numeric and boolean conditions', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          'nested.number': { $gt: 100 },
-          'nested.boolean': true,
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { 'nested.number': { $gt: 100 }, 'nested.boolean': true },
         });
         expect(results.length).toBe(1);
         expect(results[0]?.metadata?.nested?.number).toBeGreaterThan(100);
@@ -493,10 +544,10 @@ describe('CloudflareVector', () => {
       }, 10000);
 
       it('handles multiple nested field comparisons', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          'nested.string': 'premium',
-          'nested.number': { $lt: 200 },
-          'nested.boolean': true,
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { 'nested.string': 'premium', 'nested.number': { $lt: 200 }, 'nested.boolean': true },
         });
         expect(results.length).toBe(2);
         const result = results[0]?.metadata?.nested;
@@ -506,8 +557,10 @@ describe('CloudflareVector', () => {
       }, 10000);
 
       it('handles $in with nested string values', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          'nested.string': { $in: ['premium', 'basic'] },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { 'nested.string': { $in: ['premium', 'basic'] } },
         });
         expect(results.length).toBe(4);
         results.forEach(result => {
@@ -518,17 +571,20 @@ describe('CloudflareVector', () => {
 
     describe('String Operations', () => {
       it('handles string numbers in numeric comparisons', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          price: { $gt: '150' }, // String number
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { price: { $gt: '150' } }, // String number
         });
         expect(results.length).toBe(1);
         expect(Number(results[0]?.metadata?.price)).toBeGreaterThan(150);
       });
 
       it('handles mixed numeric and string comparisons', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          price: { $gt: 100 },
-          category: { $in: ['electronics'] },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { price: { $gt: 100 }, category: { $in: ['electronics'] } },
         });
         expect(results.length).toBe(1);
         expect(Number(results[0]?.metadata?.price)).toBeGreaterThan(100);
@@ -538,16 +594,20 @@ describe('CloudflareVector', () => {
 
     describe('Filter Validation and Edge Cases', () => {
       it('handles numeric zero values correctly', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          rating: { $eq: 0 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { rating: { $eq: 0 } },
         });
         expect(results.length).toBe(1);
         expect(results[0]?.metadata?.rating).toBe(0);
       });
 
       it('handles multiple conditions on same field', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          price: { $gt: 75, $lt: 200 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { price: { $gt: 75, $lt: 200 } },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -558,16 +618,20 @@ describe('CloudflareVector', () => {
       });
 
       it('handles exact numeric equality', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          price: { $eq: 100 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { price: { $eq: 100 } },
         });
         expect(results.length).toBe(1);
         expect(results[0]?.metadata?.price).toBe(100);
       });
 
       it('handles boundary conditions in ranges', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          price: { $gte: 75, $lte: 75 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { price: { $gte: 75, $lte: 75 } },
         });
         expect(results.length).toBe(1);
         expect(results[0]?.metadata?.price).toBe(75);
@@ -576,16 +640,20 @@ describe('CloudflareVector', () => {
 
     describe('String Range Queries', () => {
       it('handles lexicographical ordering in string range queries', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          code: { $gt: 'A123', $lt: 'C789' },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { code: { $gt: 'A123', $lt: 'C789' } },
         });
         expect(results.length).toBe(1);
         expect(results[0]?.metadata?.code).toBe('B456');
       }, 5000);
 
       it('handles string range queries with special characters', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          code: { $gte: 'A', $lt: 'C' },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { code: { $gte: 'A', $lt: 'C' } },
         });
         expect(results.length).toBe(2);
         results.forEach(result => {
@@ -596,15 +664,19 @@ describe('CloudflareVector', () => {
 
     describe('Null and Special Values', () => {
       it('handles $in with null values', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          optionalField: { $in: [null, 'exists'] },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { optionalField: { $in: [null, 'exists'] } },
         });
         expect(results.length).toBe(1);
       }, 5000);
 
       it('handles $ne with null values', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          optionalField: { $ne: null },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { optionalField: { $ne: null } },
         });
         expect(results.length).toBe(4);
         expect(results[0]?.metadata?.optionalField).toBe('exists');
@@ -613,16 +685,19 @@ describe('CloudflareVector', () => {
 
     describe('Mixed Type Arrays and Values', () => {
       it('handles $in with mixed type arrays', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          mixedField: { $in: ['string value', 10, null] },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { mixedField: { $in: ['string value', 10, null] } },
         });
         expect(results.length).toBe(2);
       }, 5000);
 
       it('combines different types of filters', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {
-          mixedField: { $in: ['string value', true] },
-          price: { $eq: 100 },
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: { mixedField: { $in: ['string value', true] }, price: { $eq: 100 } },
         });
         expect(results.length).toBe(1);
       }, 5000);
@@ -638,7 +713,13 @@ describe('CloudflareVector', () => {
           'nested.string': longString.slice(0, 200),
         };
 
-        await expect(vectorDB.query(testIndexName2, createVector(0, 1.0), 10, filter)).resolves.toBeDefined();
+        await expect(
+          vectorDB.query({
+            indexName: testIndexName2,
+            queryVector: createVector(0, 1.0),
+            filter,
+          }),
+        ).resolves.toBeDefined();
       }, 5000);
 
       it('handles valid range query combinations', async () => {
@@ -650,30 +731,201 @@ describe('CloudflareVector', () => {
         ];
 
         for (const filter of validRangeCombinations) {
-          await expect(vectorDB.query(testIndexName2, createVector(0, 1.0), 10, filter)).resolves.toBeDefined();
+          await expect(
+            vectorDB.query({
+              indexName: testIndexName2,
+              queryVector: createVector(0, 1.0),
+              filter,
+            }),
+          ).resolves.toBeDefined();
         }
       }, 5000);
 
       it('should handle undefined filter', async () => {
-        const results1 = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, undefined);
-        const results2 = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10);
+        const results1 = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: undefined,
+        });
+        const results2 = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+        });
         expect(results1).toEqual(results2);
         expect(results1.length).toBeGreaterThan(0);
       });
 
       it('should handle empty object filter', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, {});
-        const results2 = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10);
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: {},
+        });
+        const results2 = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+        });
         expect(results).toEqual(results2);
         expect(results.length).toBeGreaterThan(0);
       });
 
       it('should handle null filter', async () => {
-        const results = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10, null as any);
-        const results2 = await vectorDB.query(testIndexName2, createVector(0, 1.0), 10);
+        const results = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+          filter: null,
+        });
+        const results2 = await vectorDB.query({
+          indexName: testIndexName2,
+          queryVector: createVector(0, 1.0),
+        });
         expect(results).toEqual(results2);
         expect(results.length).toBeGreaterThan(0);
       });
     });
-  }, 3000000);
+  }, 800000);
+  describe('Deprecation Warnings', () => {
+    const indexName = 'testdeprecationwarnings';
+
+    const indexName2 = 'testdeprecationwarnings2';
+
+    const indexName3 = 'testdeprecationwarnings3';
+
+    const indexName4 = 'testdeprecationwarnings4';
+
+    let warnSpy;
+
+    beforeAll(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
+      }
+      try {
+        await vectorDB.deleteIndex(indexName3);
+      } catch {
+        // Ignore errors if index doesn't exist
+      }
+      try {
+        await vectorDB.deleteIndex(indexName4);
+      } catch {
+        // Ignore errors if index doesn't exist
+      }
+      await vectorDB.createIndex({ indexName: indexName, dimension: VECTOR_DIMENSION });
+      await waitUntilReady(vectorDB, indexName);
+    });
+
+    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
+      }
+      try {
+        await vectorDB.deleteIndex(indexName3);
+      } catch {
+        // Ignore errors if index doesn't exist
+      }
+      try {
+        await vectorDB.deleteIndex(indexName4);
+      } 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 (error) {
+        console.warn('Failed to delete test index:', error);
+      }
+    });
+
+    it('should show deprecation warning when using individual args for createIndex', async () => {
+      await vectorDB.createIndex(indexName2, VECTOR_DIMENSION, 'cosine');
+      await waitUntilReady(vectorDB, indexName2);
+      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, [createVector(0, 1.0)], [{ 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, createVector(0, 1.0), 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: createVector(0, 1.0),
+        topK: 5,
+      });
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should not show deprecation warning when using object param for createIndex', async () => {
+      await vectorDB.createIndex({
+        indexName: indexName3,
+        dimension: VECTOR_DIMENSION,
+        metric: 'cosine',
+      });
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should not show deprecation warning when using object param for upsert', async () => {
+      await vectorDB.upsert({
+        indexName,
+        vectors: [createVector(0, 1.0)],
+        metadata: [{ test: 'data' }],
+      });
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it('should maintain backward compatibility with individual args', async () => {
+      // Query
+      const queryResults = await vectorDB.query(indexName, createVector(0, 1.0), 5);
+      expect(Array.isArray(queryResults)).toBe(true);
+
+      // CreateIndex
+      await expect(vectorDB.createIndex(indexName4, VECTOR_DIMENSION, 'cosine')).resolves.not.toThrow();
+      await waitUntilReady(vectorDB, indexName4);
+      // Upsert
+      const upsertResults = await vectorDB.upsert({
+        indexName,
+        vectors: [createVector(0, 1.0)],
+        metadata: [{ test: 'data' }],
+      });
+      expect(Array.isArray(upsertResults)).toBe(true);
+      expect(upsertResults).toHaveLength(1);
+    });
+  }, 80000);
 });

package/src/vector/index.ts

@@ -1,6 +1,12 @@
-import type { Filter } from '@mastra/core/filter';
 import { MastraVector } from '@mastra/core/vector';
-import type { QueryResult } from '@mastra/core/vector';
+import type {
+  QueryResult,
+  CreateIndexParams,
+  UpsertVectorParams,
+  QueryVectorParams,
+  ParamsToArgs,
+} from '@mastra/core/vector';
+import type { VectorFilter } from '@mastra/core/vector/filter';
 import Cloudflare from 'cloudflare';
 
 import { VectorizeFilterTranslator } from './filter';
@@ -18,12 +24,11 @@ export class CloudflareVector extends MastraVector {
     });
   }
 
-  async upsert(
-    indexName: string,
-    vectors: number[][],
-    metadata?: Record<string, any>[],
-    ids?: string[],
-  ): Promise<string[]> {
+  async upsert(...args: ParamsToArgs<UpsertVectorParams>): Promise<string[]> {
+    const params = this.normalizeArgs<UpsertVectorParams>('upsert', args);
+
+    const { indexName, vectors, metadata, ids } = params;
+
     const generatedIds = ids || vectors.map(() => crypto.randomUUID());
 
     // Create NDJSON string - each line is a JSON object
@@ -52,17 +57,16 @@ export class CloudflareVector extends MastraVector {
     return generatedIds;
   }
 
-  transformFilter(filter?: Filter) {
+  transformFilter(filter?: VectorFilter) {
     const translator = new VectorizeFilterTranslator();
-    const translatedFilter = translator.translate(filter);
-    return translatedFilter;
+    return translator.translate(filter);
   }
 
-  async createIndex(
-    indexName: string,
-    dimension: number,
-    metric: 'cosine' | 'euclidean' | 'dotproduct' = 'cosine',
-  ): Promise<void> {
+  async createIndex(...args: ParamsToArgs<CreateIndexParams>): Promise<void> {
+    const params = this.normalizeArgs<CreateIndexParams>('createIndex', args);
+
+    const { indexName, dimension, metric = 'cosine' } = params;
+
     await this.client.vectorize.indexes.create({
       account_id: this.accountId,
       config: {
@@ -73,14 +77,12 @@ export class CloudflareVector extends MastraVector {
     });
   }
 
-  async query(
-    indexName: string,
-    queryVector: number[],
-    topK: number = 10,
-    filter?: Filter,
-    includeVector: boolean = false,
-  ): Promise<QueryResult[]> {
-    const translatedFilter = this.transformFilter(filter);
+  async query(...args: ParamsToArgs<QueryVectorParams>): Promise<QueryResult[]> {
+    const params = this.normalizeArgs<QueryVectorParams>('query', args);
+
+    const { indexName, queryVector, topK = 10, filter, includeVector = false } = params;
+
+    const translatedFilter = this.transformFilter(filter) ?? {};
     const response = await this.client.vectorize.indexes.query(indexName, {
       account_id: this.accountId,
       vector: queryVector,