@mastra/couchbase 0.0.0-trigger-playground-ui-package-20250506151043 → 0.0.0-vector-query-sources-20250516172905

package/src/vector/index.ts

@@ -5,9 +5,14 @@ import type {
   CreateIndexParams,
   UpsertVectorParams,
   QueryVectorParams,
+  DescribeIndexParams,
+  ParamsToArgs,
+  DeleteIndexParams,
+  DeleteVectorParams,
+  UpdateVectorParams,
 } from '@mastra/core/vector';
 import type { Bucket, Cluster, Collection, Scope } from 'couchbase';
-import { connect, SearchRequest, VectorQuery, VectorSearch } from 'couchbase';
+import { MutateInSpec, connect, SearchRequest, VectorQuery, VectorSearch } from 'couchbase';
 
 type MastraMetric = 'cosine' | 'euclidean' | 'dotproduct';
 type CouchbaseMetric = 'cosine' | 'l2_norm' | 'dot_product';
@@ -17,6 +22,15 @@ export const DISTANCE_MAPPING: Record<MastraMetric, CouchbaseMetric> = {
   dotproduct: 'dot_product',
 };
 
+export type CouchbaseVectorParams = {
+  connectionString: string;
+  username: string;
+  password: string;
+  bucketName: string;
+  scopeName: string;
+  collectionName: string;
+};
+
 export class CouchbaseVector extends MastraVector {
   private clusterPromise: Promise<Cluster>;
   private cluster: Cluster;
@@ -28,19 +42,66 @@ export class CouchbaseVector extends MastraVector {
   private scope: Scope;
   private vector_dimension: number;
 
+  /**
+   * @deprecated Passing parameters as positional arguments is deprecated.
+   * Use the object parameter instead. This signature will be removed on May 20th, 2025.
+   */
   constructor(
-    cnn_string: string,
+    connectionString: string,
     username: string,
     password: string,
     bucketName: string,
     scopeName: string,
     collectionName: string,
+  );
+  constructor(params: CouchbaseVectorParams);
+  constructor(
+    paramsOrConnectionString: CouchbaseVectorParams | string,
+    username?: string,
+    password?: string,
+    bucketName?: string,
+    scopeName?: string,
+    collectionName?: string,
   ) {
+    let connectionString_: string,
+      username_: string,
+      password_: string,
+      bucketName_: string,
+      scopeName_: string,
+      collectionName_: string;
+
+    if (
+      typeof paramsOrConnectionString === 'object' &&
+      paramsOrConnectionString !== null &&
+      'connectionString' in paramsOrConnectionString
+    ) {
+      // Object params (preferred)
+      connectionString_ = paramsOrConnectionString.connectionString as string;
+      username_ = paramsOrConnectionString.username;
+      password_ = paramsOrConnectionString.password;
+      bucketName_ = paramsOrConnectionString.bucketName;
+      scopeName_ = paramsOrConnectionString.scopeName;
+      collectionName_ = paramsOrConnectionString.collectionName;
+    } else {
+      // Positional args (deprecated)
+      if (arguments.length > 1) {
+        console.warn(
+          'Deprecation Warning: CouchbaseVector constructor positional arguments are deprecated. Please use a single object parameter instead. This signature will be removed on May 20th, 2025.',
+        );
+      }
+      connectionString_ = paramsOrConnectionString as string;
+      username_ = username!;
+      password_ = password!;
+      bucketName_ = bucketName!;
+      scopeName_ = scopeName!;
+      collectionName_ = collectionName!;
+    }
+
     super();
 
-    const baseClusterPromise = connect(cnn_string, {
-      username,
-      password,
+    const baseClusterPromise = connect(connectionString_, {
+      username: username_,
+      password: password_,
       configProfile: 'wanDevelopment',
     });
 
@@ -53,9 +114,9 @@ export class CouchbaseVector extends MastraVector {
         },
       }) ?? baseClusterPromise;
     this.cluster = null as unknown as Cluster;
-    this.bucketName = bucketName;
-    this.collectionName = collectionName;
-    this.scopeName = scopeName;
+    this.bucketName = bucketName_;
+    this.collectionName = collectionName_;
+    this.scopeName = scopeName_;
     this.collection = null as unknown as Collection;
     this.bucket = null as unknown as Bucket;
     this.scope = null as unknown as Scope;
@@ -84,81 +145,92 @@ export class CouchbaseVector extends MastraVector {
       throw new Error('Dimension must be a positive integer');
     }
 
-    await this.scope.searchIndexes().upsertIndex({
-      name: indexName,
-      sourceName: this.bucketName,
-      type: 'fulltext-index',
-      params: {
-        doc_config: {
-          docid_prefix_delim: '',
-          docid_regexp: '',
-          mode: 'scope.collection.type_field',
-          type_field: 'type',
-        },
-        mapping: {
-          default_analyzer: 'standard',
-          default_datetime_parser: 'dateTimeOptional',
-          default_field: '_all',
-          default_mapping: {
-            dynamic: true,
-            enabled: false,
+    try {
+      await this.scope.searchIndexes().upsertIndex({
+        name: indexName,
+        sourceName: this.bucketName,
+        type: 'fulltext-index',
+        params: {
+          doc_config: {
+            docid_prefix_delim: '',
+            docid_regexp: '',
+            mode: 'scope.collection.type_field',
+            type_field: 'type',
           },
-          default_type: '_default',
-          docvalues_dynamic: true, // [Doc](https://docs.couchbase.com/server/current/search/search-index-params.html#params) mentions this attribute is required for vector search to return the indexed field
-          index_dynamic: true,
-          store_dynamic: true, // [Doc](https://docs.couchbase.com/server/current/search/search-index-params.html#params) mentions this attribute is required for vector search to return the indexed field
-          type_field: '_type',
-          types: {
-            [`${this.scopeName}.${this.collectionName}`]: {
+          mapping: {
+            default_analyzer: 'standard',
+            default_datetime_parser: 'dateTimeOptional',
+            default_field: '_all',
+            default_mapping: {
               dynamic: true,
-              enabled: true,
-              properties: {
-                embedding: {
-                  enabled: true,
-                  fields: [
-                    {
-                      dims: dimension,
-                      index: true,
-                      name: 'embedding',
-                      similarity: DISTANCE_MAPPING[metric],
-                      type: 'vector',
-                      vector_index_optimized_for: 'recall',
-                      store: true, // CHANGED due to https://docs.couchbase.com/server/current/search/search-index-params.html#fields
-                      docvalues: true, // CHANGED due to https://docs.couchbase.com/server/current/search/search-index-params.html#fields
-                      include_term_vectors: true, // CHANGED due to https://docs.couchbase.com/server/current/search/search-index-params.html#fields
-                    },
-                  ],
-                },
-                content: {
-                  enabled: true,
-                  fields: [
-                    {
-                      index: true,
-                      name: 'content',
-                      store: true,
-                      type: 'text',
-                    },
-                  ],
+              enabled: false,
+            },
+            default_type: '_default',
+            docvalues_dynamic: true, // [Doc](https://docs.couchbase.com/server/current/search/search-index-params.html#params) mentions this attribute is required for vector search to return the indexed field
+            index_dynamic: true,
+            store_dynamic: true, // [Doc](https://docs.couchbase.com/server/current/search/search-index-params.html#params) mentions this attribute is required for vector search to return the indexed field
+            type_field: '_type',
+            types: {
+              [`${this.scopeName}.${this.collectionName}`]: {
+                dynamic: true,
+                enabled: true,
+                properties: {
+                  embedding: {
+                    enabled: true,
+                    fields: [
+                      {
+                        dims: dimension,
+                        index: true,
+                        name: 'embedding',
+                        similarity: DISTANCE_MAPPING[metric],
+                        type: 'vector',
+                        vector_index_optimized_for: 'recall',
+                        store: true, // CHANGED due to https://docs.couchbase.com/server/current/search/search-index-params.html#fields
+                        docvalues: true, // CHANGED due to https://docs.couchbase.com/server/current/search/search-index-params.html#fields
+                        include_term_vectors: true, // CHANGED due to https://docs.couchbase.com/server/current/search/search-index-params.html#fields
+                      },
+                    ],
+                  },
+                  content: {
+                    enabled: true,
+                    fields: [
+                      {
+                        index: true,
+                        name: 'content',
+                        store: true,
+                        type: 'text',
+                      },
+                    ],
+                  },
                 },
               },
             },
           },
+          store: {
+            indexType: 'scorch',
+            segmentVersion: 16,
+          },
         },
-        store: {
-          indexType: 'scorch',
-          segmentVersion: 16,
+        sourceUuid: '',
+        sourceParams: {},
+        sourceType: 'gocbcore',
+        planParams: {
+          maxPartitionsPerPIndex: 64,
+          indexPartitions: 16,
+          numReplicas: 0,
         },
-      },
-      sourceUuid: '',
-      sourceParams: {},
-      sourceType: 'gocbcore',
-      planParams: {
-        maxPartitionsPerPIndex: 64,
-        indexPartitions: 16,
-        numReplicas: 0,
-      },
-    });
-    this.vector_dimension = dimension;
+      });
+      this.vector_dimension = dimension;
+    } catch (error: any) {
+      // Check for 'already exists' error (Couchbase may throw a 400 or 409, or have a message)
+      const message = error?.message || error?.toString();
+      if (message && message.toLowerCase().includes('index exists')) {
+        // Fetch index info and check dimension
+        await this.validateExistingIndex(indexName, dimension, metric);
+        return;
+      }
+      throw error;
+    }
   }
 
   async upsert(params: UpsertVectorParams): Promise<string[]> {
@@ -244,7 +316,16 @@ export class CouchbaseVector extends MastraVector {
     return indexes?.map(index => index.name) || [];
   }
 
-  async describeIndex(indexName: string): Promise<IndexStats> {
+  /**
+   * Retrieves statistics about a vector index.
+   *
+   * @param params - The parameters for describing an index
+   * @param params.indexName - The name of the index to describe
+   * @returns A promise that resolves to the index statistics including dimension, count and metric
+   */
+  async describeIndex(...args: ParamsToArgs<DescribeIndexParams>): Promise<IndexStats> {
+    const params = this.normalizeArgs<DescribeIndexParams>('describeIndex', args);
+    const { indexName } = params;
     await this.getCollection();
     if (!(await this.listIndexes()).includes(indexName)) {
       throw new Error(`Index ${indexName} does not exist`);
@@ -265,7 +346,9 @@ export class CouchbaseVector extends MastraVector {
     };
   }
 
-  async deleteIndex(indexName: string): Promise<void> {
+  async deleteIndex(...args: ParamsToArgs<DeleteIndexParams>): Promise<void> {
+    const params = this.normalizeArgs<DeleteIndexParams>('deleteIndex', args);
+    const { indexName } = params;
     await this.getCollection();
     if (!(await this.listIndexes()).includes(indexName)) {
       throw new Error(`Index ${indexName} does not exist`);
@@ -273,4 +356,68 @@ export class CouchbaseVector extends MastraVector {
     await this.scope.searchIndexes().dropIndex(indexName);
     this.vector_dimension = null as unknown as number;
   }
+
+  /**
+   * Updates a vector by its ID with the provided vector and/or metadata.
+   * @param indexName - The name of the index containing the vector.
+   * @param id - The ID of the vector to update.
+   * @param update - An object containing the vector and/or metadata to update.
+   * @param update.vector - An optional array of numbers representing the new vector.
+   * @param update.metadata - An optional record containing the new metadata.
+   * @returns A promise that resolves when the update is complete.
+   * @throws Will throw an error if no updates are provided or if the update operation fails.
+   */
+  async updateVector(...args: ParamsToArgs<UpdateVectorParams>): Promise<void> {
+    const params = this.normalizeArgs<UpdateVectorParams>('updateVector', args);
+    const { id, update } = params;
+    if (!update.vector && !update.metadata) {
+      throw new Error('No updates provided');
+    }
+    if (update.vector && this.vector_dimension && update.vector.length !== this.vector_dimension) {
+      throw new Error('Vector dimension mismatch');
+    }
+    const collection = await this.getCollection();
+
+    // Check if document exists
+    try {
+      await collection.get(id);
+    } catch (err: any) {
+      if (err.code === 13 || err.message?.includes('document not found')) {
+        throw new Error(`Vector with id ${id} does not exist`);
+      }
+      throw err;
+    }
+
+    const specs: MutateInSpec[] = [];
+    if (update.vector) specs.push(MutateInSpec.replace('embedding', update.vector));
+    if (update.metadata) specs.push(MutateInSpec.replace('metadata', update.metadata));
+
+    await collection.mutateIn(id, specs);
+  }
+
+  /**
+   * Deletes a vector by its ID.
+   * @param indexName - The name of the index containing the vector.
+   * @param id - The ID of the vector to delete.
+   * @returns A promise that resolves when the deletion is complete.
+   * @throws Will throw an error if the deletion operation fails.
+   */
+  async deleteVector(...args: ParamsToArgs<DeleteVectorParams>): Promise<void> {
+    const params = this.normalizeArgs<DeleteVectorParams>('deleteVector', args);
+
+    const { id } = params;
+    const collection = await this.getCollection();
+
+    // Check if document exists
+    try {
+      await collection.get(id);
+    } catch (err: any) {
+      if (err.code === 13 || err.message?.includes('document not found')) {
+        throw new Error(`Vector with id ${id} does not exist`);
+      }
+      throw err;
+    }
+
+    await collection.remove(id);
+  }
 }

package/src/vector/index.unit.test.ts

@@ -165,14 +165,14 @@ describe('Unit Testing CouchbaseVector', () => {
     });
 
     it('should connect to couchbase', async () => {
-      couchbase_client = new CouchbaseVector(
-        'COUCHBASE_CONNECTION_STRING',
-        'COUCHBASE_USERNAME',
-        'COUCHBASE_PASSWORD',
-        test_bucketName,
-        test_scopeName,
-        test_collectionName,
-      );
+      couchbase_client = new CouchbaseVector({
+        connectionString: 'COUCHBASE_CONNECTION_STRING',
+        username: 'COUCHBASE_USERNAME',
+        password: 'COUCHBASE_PASSWORD',
+        bucketName: test_bucketName,
+        scopeName: test_scopeName,
+        collectionName: test_collectionName,
+      });
       expect(mockCouchbaseConnectFn).toHaveBeenCalledTimes(1);
       expect(mockCouchbaseConnectFn).toHaveBeenCalledWith('COUCHBASE_CONNECTION_STRING', {
         username: 'COUCHBASE_USERNAME',
@@ -200,14 +200,14 @@ describe('Unit Testing CouchbaseVector', () => {
   describe('Index Operations', () => {
     beforeAll(async () => {
       clearAllMocks();
-      couchbase_client = new CouchbaseVector(
-        'COUCHBASE_CONNECTION_STRING',
-        'COUCHBASE_USERNAME',
-        'COUCHBASE_PASSWORD',
-        test_bucketName,
-        test_scopeName,
-        test_collectionName,
-      );
+      couchbase_client = new CouchbaseVector({
+        connectionString: 'COUCHBASE_CONNECTION_STRING',
+        username: 'COUCHBASE_USERNAME',
+        password: 'COUCHBASE_PASSWORD',
+        bucketName: test_bucketName,
+        scopeName: test_scopeName,
+        collectionName: test_collectionName,
+      });
       await couchbase_client.getCollection();
     });
 
@@ -311,7 +311,7 @@ describe('Unit Testing CouchbaseVector', () => {
     }, 50000);
 
     it('should describe index', async () => {
-      const stats = await couchbase_client.describeIndex(test_indexName);
+      const stats = await couchbase_client.describeIndex({ indexName: test_indexName });
 
       expect(mockScopeSearchIndexesFn).toHaveBeenCalledTimes(2);
 
@@ -328,7 +328,7 @@ describe('Unit Testing CouchbaseVector', () => {
     }, 50000);
 
     it('should delete index', async () => {
-      await couchbase_client.deleteIndex(test_indexName);
+      await couchbase_client.deleteIndex({ indexName: test_indexName });
 
       expect(mockScopeSearchIndexesFn).toHaveBeenCalledTimes(2);
 
@@ -343,14 +343,14 @@ describe('Unit Testing CouchbaseVector', () => {
 
   describe('Vector Operations', () => {
     beforeAll(async () => {
-      couchbase_client = new CouchbaseVector(
-        'COUCHBASE_CONNECTION_STRING',
-        'COUCHBASE_USERNAME',
-        'COUCHBASE_PASSWORD',
-        test_bucketName,
-        test_scopeName,
-        test_collectionName,
-      );
+      couchbase_client = new CouchbaseVector({
+        connectionString: 'COUCHBASE_CONNECTION_STRING',
+        username: 'COUCHBASE_USERNAME',
+        password: 'COUCHBASE_PASSWORD',
+        bucketName: test_bucketName,
+        scopeName: test_scopeName,
+        collectionName: test_collectionName,
+      });
 
       await couchbase_client.getCollection();
     });
@@ -510,14 +510,14 @@ describe('Unit Testing CouchbaseVector', () => {
   describe('Error Cases and Edge Cases', () => {
     beforeAll(async () => {
       clearAllMocks();
-      couchbase_client = new CouchbaseVector(
-        'COUCHBASE_CONNECTION_STRING',
-        'COUCHBASE_USERNAME',
-        'COUCHBASE_PASSWORD',
-        test_bucketName,
-        test_scopeName,
-        test_collectionName,
-      );
+      couchbase_client = new CouchbaseVector({
+        connectionString: 'COUCHBASE_CONNECTION_STRING',
+        username: 'COUCHBASE_USERNAME',
+        password: 'COUCHBASE_PASSWORD',
+        bucketName: test_bucketName,
+        scopeName: test_scopeName,
+        collectionName: test_collectionName,
+      });
       await couchbase_client.getCollection();
     });
 
@@ -542,13 +542,13 @@ describe('Unit Testing CouchbaseVector', () => {
     });
 
     it('should throw error when describing a non-existent index', async () => {
-      await expect(couchbase_client.describeIndex('non_existent_index')).rejects.toThrow(
+      await expect(couchbase_client.describeIndex({ indexName: 'non_existent_index' })).rejects.toThrow(
         `Index non_existent_index does not exist`,
       );
     });
 
     it('should throw error when deleting a non-existent index', async () => {
-      await expect(couchbase_client.deleteIndex('non_existent_index')).rejects.toThrow(
+      await expect(couchbase_client.deleteIndex({ indexName: 'non_existent_index' })).rejects.toThrow(
         `Index non_existent_index does not exist`,
       );
     });
@@ -577,14 +577,14 @@ describe('Unit Testing CouchbaseVector', () => {
   describe('Vector Dimension Tracking', () => {
     beforeEach(async () => {
       clearAllMocks();
-      couchbase_client = new CouchbaseVector(
-        'COUCHBASE_CONNECTION_STRING',
-        'COUCHBASE_USERNAME',
-        'COUCHBASE_PASSWORD',
-        test_bucketName,
-        test_scopeName,
-        test_collectionName,
-      );
+      couchbase_client = new CouchbaseVector({
+        connectionString: 'COUCHBASE_CONNECTION_STRING',
+        username: 'COUCHBASE_USERNAME',
+        password: 'COUCHBASE_PASSWORD',
+        bucketName: test_bucketName,
+        scopeName: test_scopeName,
+        collectionName: test_collectionName,
+      });
       await couchbase_client.getCollection();
     });
 
@@ -637,7 +637,7 @@ describe('Unit Testing CouchbaseVector', () => {
       clearAllMocks();
 
       // Delete the index
-      await couchbase_client.deleteIndex(test_indexName);
+      await couchbase_client.deleteIndex({ indexName: test_indexName });
 
       // Verify dimension is reset
       expect((couchbase_client as any).vector_dimension).toBeNull();
@@ -647,14 +647,14 @@ describe('Unit Testing CouchbaseVector', () => {
   describe('Implementation Details', () => {
     beforeEach(async () => {
       clearAllMocks();
-      couchbase_client = new CouchbaseVector(
-        'COUCHBASE_CONNECTION_STRING',
-        'COUCHBASE_USERNAME',
-        'COUCHBASE_PASSWORD',
-        test_bucketName,
-        test_scopeName,
-        test_collectionName,
-      );
+      couchbase_client = new CouchbaseVector({
+        connectionString: 'COUCHBASE_CONNECTION_STRING',
+        username: 'COUCHBASE_USERNAME',
+        password: 'COUCHBASE_PASSWORD',
+        bucketName: test_bucketName,
+        scopeName: test_scopeName,
+        collectionName: test_collectionName,
+      });
       await couchbase_client.getCollection();
     });
 
@@ -713,7 +713,7 @@ describe('Unit Testing CouchbaseVector', () => {
           },
         });
 
-        const stats = await couchbase_client.describeIndex(test_indexName);
+        const stats = await couchbase_client.describeIndex({ indexName: test_indexName });
         expect(stats.metric).toBe(mastraMetric);
       }
     });