@mastra/couchbase 0.0.2-alpha.0

package/.turbo/turbo-build.log

@@ -0,0 +1,23 @@
+
+> @mastra/couchbase@0.0.2-alpha.0 build /home/runner/work/mastra/mastra/stores/couchbase
+> tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting
+
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.4.0
+TSC Build start
+TSC ⚡️ Build success in 5560ms
+DTS Build start
+CLI Target: es2022
+Analysis will use the bundled TypeScript version 5.8.3
+Writing package typings: /home/runner/work/mastra/mastra/stores/couchbase/dist/_tsup-dts-rollup.d.ts
+Analysis will use the bundled TypeScript version 5.8.3
+Writing package typings: /home/runner/work/mastra/mastra/stores/couchbase/dist/_tsup-dts-rollup.d.cts
+DTS ⚡️ Build success in 8777ms
+CLI Cleaning output folder
+ESM Build start
+CJS Build start
+CJS dist/index.cjs 8.15 KB
+CJS ⚡️ Build success in 496ms
+ESM dist/index.js 8.09 KB
+ESM ⚡️ Build success in 496ms

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @mastra/couchbase
+
+## 0.0.2-alpha.0
+
+### Patch Changes
+
+- 106a2ab: Added integration for Couchbase Vector Store
+- Updated dependencies [3d2fb5c]
+- Updated dependencies [7eeb2bc]
+- Updated dependencies [8607972]
+- Updated dependencies [7eeb2bc]
+- Updated dependencies [fba031f]
+  - @mastra/core@0.9.2-alpha.5

package/LICENSE.md

@@ -0,0 +1,46 @@
+# Elastic License 2.0 (ELv2)
+
+Copyright (c) 2025 Mastra AI, Inc.
+
+**Acceptance**
+By using the software, you agree to all of the terms and conditions below.
+
+**Copyright License**
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below
+
+**Limitations**
+You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+**Patents**
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+**Notices**
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
+
+**No Other Rights**
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+**Termination**
+If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+**No Liability**
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+**Definitions**
+The _licensor_ is the entity offering these terms, and the _software_ is the software the licensor makes available under these terms, including any portion of it.
+
+_you_ refers to the individual or entity agreeing to these terms.
+
+_your company_ is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. _control_ means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+_your licenses_ are all the licenses granted to you for the software under these terms.
+
+_use_ means anything you do with the software requiring one of your licenses.
+
+_trademark_ means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,267 @@
+# @mastra/couchbase
+
+A Mastra vector store implementation for Couchbase, enabling powerful vector similarity search capabilities using the official Couchbase Node.js SDK (v4+). Leverages Couchbase Server's built-in Vector Search feature (available in version 7.6.4+).
+
+## Features
+
+- 🚀 Vector similarity search powered by Couchbase Search Service.
+- 📐 Supports Cosine, Euclidean (L2 Norm), and Dot Product distance metrics.
+- 📄 Stores vectors and associated metadata within Couchbase documents in a specified Collection.
+- 🔧 Manages Couchbase Search Indexes specifically configured for vector search (Create, List, Describe, Delete).
+- 🆔 Automatic UUID generation for documents if IDs are not provided during upsert.
+- ☁️ Compatible with both self-hosted Couchbase Server (7.6.4+) and Couchbase Capella.
+- ⚙️ Uses the official Couchbase Node.js SDK v4+.
+- 📈 Built-in telemetry support for tracing operations via `@mastra/core`.
+
+## Prerequisites
+
+- Couchbase Server (Version 7.6.4 or higher) or Couchbase Capella cluster with the **Search Service** enabled.
+- A configured **Bucket**, **Scope**, and **Collection** within your Couchbase cluster where vectors and metadata will be stored.
+- Couchbase user credentials (`username`, `password`) with permissions to ([Docs](https://docs.couchbase.com/cloud/get-started/connect.html#prerequisites)):
+  - Connect to the cluster.
+  - Read/write documents in the specified Collection (`kv` role usually covers this).
+  - Manage Search Indexes (`search_admin` role on the relevant bucket/scope).
+- Node.js (v18+ recommended).
+
+## Installation
+
+```bash
+npm install @mastra/couchbase
+# or using pnpm
+pnpm add @mastra/couchbase
+# or using yarn
+yarn add @mastra/couchbase
+```
+
+## Getting Started: A Quick Tutorial
+
+Let's set up `@mastra/couchbase` to store and search vectors in your Couchbase cluster.
+
+**Step 1: Connect to Your Cluster**
+
+Instantiate `CouchbaseVector` with your cluster details.
+
+```typescript
+import { CouchbaseVector } from '@mastra/couchbase';
+
+const connectionString = 'couchbases://your_cluster_host?ssl=no_verify'; // Use couchbases:// for Capella/TLS, couchbase:// for local/non-TLS
+const username = 'your_couchbase_user';
+const password = 'your_couchbase_password';
+const bucketName = 'your_vector_bucket';
+const scopeName = '_default'; // Or your custom scope name
+const collectionName = 'vector_data'; // Or your custom collection name
+
+const vectorStore = new CouchbaseVector(connectionString, username, password, bucketName, scopeName, collectionName);
+
+console.log('CouchbaseVector instance created. Connecting...');
+```
+
+_Note_: The actual connection to Couchbase happens lazily upon the first operation.
+
+**Step 2: Create a Vector Search Index**
+
+Define and create a Search Index specifically for vector search on your collection.
+
+```typescript
+const indexName = 'my_vector_search_index';
+const vectorDimension = 1536; // Example: OpenAI embedding dimension
+
+try {
+  await vectorStore.createIndex({
+    indexName: indexName,
+    dimension: vectorDimension,
+    metric: 'cosine', // Or 'euclidean', 'dotproduct'
+  });
+  console.log(`Search index '${indexName}' created or updated successfully.`);
+} catch (error) {
+  console.error(`Failed to create index '${indexName}':`, error);
+}
+```
+
+_Note_: Index creation in Couchbase is asynchronous. It might take a short while for the index to become fully built and queryable.
+
+_Best practice_: Implement a delay or polling mechanism to ensure the index is ready using simple delay approach (`await new Promise(resolve => setTimeout(resolve, 2000));`) or implement a more robust solution that polls the index status
+
+**Step 3: Add Your Vectors (Upsert Documents)**
+
+Store your vectors and metadata as documents in the designated Couchbase collection.
+
+```typescript
+const vectors = [
+  Array(vectorDimension).fill(0.1), // Replace with your actual vectors
+  Array(vectorDimension).fill(0.2),
+];
+const metadata = [
+  { source: 'doc1.txt', page: 1, category: 'finance' },
+  { source: 'doc2.pdf', page: 5, text: 'This is the text content.', category: 'tech' }, // Example with text
+];
+
+try {
+  // IDs will be auto-generated UUIDs if not provided
+  const ids = await vectorStore.upsert({
+    indexName: indexName, // Required for dimension validation if tracked
+    vectors: vectors,
+    metadata: metadata,
+    // ids: ['custom_id_1', 'custom_id_2'] // Optionally provide your own IDs
+  });
+  console.log('Upserted documents with IDs:', ids);
+} catch (error) {
+  console.error('Failed to upsert vectors:', error);
+}
+```
+
+_Note_: For large vector batches, Couchbase may need time to process and index all documents. Consider implementing appropriate waiting periods before querying newly inserted vectors like a simple delay (`await new Promise(resolve => setTimeout(resolve, 1000));`) for smaller batches
+
+Document structure in Couchbase will resemble:
+
+```
+Document ID: <generated_or_provided_id>
+  {
+    "embedding": [0.1, ...],
+    "metadata": { "source": "doc1.txt", "page": 1, "category": "finance" }
+  }
+```
+
+```
+Document ID: <generated_or_provided_id>
+  {
+    "embedding": [0.2, ...],
+    "metadata": { "source": "doc2.pdf", "page": 5, "text": "...", "category": "tech" },
+    "content": "This is the text content." // 'content' field added if metadata.text exists
+  }
+```
+
+**Step 4: Find Similar Vectors (Query the Index)**
+
+Use the Search Index to find documents with vectors similar to your query vector.
+
+```typescript
+const queryVector = Array(vectorDimension).fill(0.15); // Your query vector
+const k = 5; // Number of nearest neighbors to retrieve
+try {
+  const results = await vectorStore.query({
+    indexName: indexName,
+    queryVector: queryVector,
+    topK: k,
+  });
+  console.log(`Found ${results.length} similar results:`, results);
+} catch (error) {
+  console.error('Failed to query vectors:', error);
+}
+```
+
+_Note_: Metadata `filter` and `includeVector` not yet supported in `query()`
+
+Results format:
+
+```
+[
+    {
+        id: string, // Document ID
+        score: number, // Similarity score (higher is better for cosine/dotproduct, lower for euclidean)
+        metadata: Record<string, any> // Fields stored in the index (typically includes 'metadata', 'content')
+    },
+    // ... more results
+]
+```
+
+**Step 5: Manage Indexes**
+
+List, inspect, or delete your vector search indexes.
+
+```typescript
+try {
+  // List all Search Indexes in the cluster (may include non-vector indexes)
+  const indexes = await vectorStore.listIndexes();
+  console.log('Available search indexes:', indexes);
+  // Get details about our specific vector index
+  for (const indexName of indexes) {
+    const stats = await vectorStore.describeIndex(indexName);
+    console.log(`Stats for index '${indexName}':`, stats);
+  }
+  // Delete the index when no longer needed
+  await vectorStore.deleteIndex(indexName);
+  console.log(`Search index '${indexName}' deleted.`);
+} catch (error) {
+  console.error('Failed to manage indexes:', error);
+}
+```
+
+_Note_: Deleting Index does NOT delete the vectors in the associated Couchbase Collection
+
+## Advanced Couchbase Vector Usage
+
+- **Distance Metrics Mapping:**
+  - The `metric` parameter in `createIndex` and `describeIndex` uses Mastra terms. These map to Couchbase index definitions as follows:
+    - `cosine` → `cosine`
+    - `euclidean` → `l2_norm`
+    - `dotproduct` → `dot_product`
+- **Index Definition Details:**
+  - The `createIndex` method constructs a Couchbase Search Index definition tailored for vector search. It indexes the `embedding` field (as type `vector`) and the `content` field (as type `text`), targeting documents within the specified `scopeName.collectionName`. It enables `store` and `docvalues` for these fields. For fine-grained control over the index definition (e.g., different analyzers, type mappings), you would need to use the Couchbase SDK or UI directly.
+- **Document Structure:**
+  - Vectors are stored in the `embedding` field.
+  - Metadata is stored in the `metadata` field.
+  - If `metadata.text` exists, it's copied to the `content` field.
+  - The `query` results currently return stored fields like `metadata` and `content` in the `metadata` property of the result object, but **not** the `embedding` field itself.
+
+## API Reference (`CouchbaseVector` Methods)
+
+- `constructor(cnn_string, username, password, bucketName, scopeName, collectionName)`: Creates a new instance and prepares the connection promise.
+- `getCollection()`: (Primarily internal) Establishes connection lazily and gets the Couchbase `Collection` object.
+- `createIndex({ indexName, dimension, metric? })`: Creates or updates a Couchbase Search Index configured for vector search on the collection.
+- `upsert({ indexName, vectors, metadata?, ids? })`: Upserts documents containing vectors and metadata into the Couchbase collection. Returns the document IDs used.
+- `query({ indexName, queryVector, topK?, filter?, includeVector? })`: Queries the specified Search Index for similar vectors using Couchbase Vector Search. **Note:** `filter` and `includeVector` options are **not currently supported**.
+- `listIndexes()`: Lists the names of all Search Indexes in the cluster. Returns fully qualified names (e.g., `bucket.scope.index`).
+- `describeIndex(indexName)`: Gets the configured dimension, metric (Mastra name), and document count (currently returns -1) for a specific Search Index (using its short name).
+- `deleteIndex(indexName)`: Deletes a Search Index (using its short name).
+
+## Configuration Details
+
+- **Required Constructor Parameters:**
+  - `cnn_string`: Couchbase connection string (e.g., `couchbases://host?ssl=no_verify`, `couchbase://localhost`). See [Couchbase SDK Docs](https://docs.couchbase.com/nodejs-sdk/current/hello-world/connect.html) for all options.
+  - `username`: Couchbase user with necessary permissions (see Prerequisites).
+  - `password`: Password for the Couchbase user.
+  - `bucketName`: Name of the target Couchbase Bucket.
+  - `scopeName`: Name of the target Scope within the Bucket.
+  - `collectionName`: Name of the target Collection within the Scope.
+- **Internal Connection Profile:** The library internally uses the `wanDevelopment` configuration profile when connecting via the Couchbase SDK. This profile adjusts certain timeouts suitable for development and some cloud environments. For production tuning, consider modifying the library or managing the SDK connection externally.
+
+## Notes & Considerations
+
+- **Couchbase Version:** This integration requires **Couchbase Server 7.6.4+** or a compatible Couchbase Capella cluster with the **Search Service enabled**.
+- **Index Creation:** The `createIndex` method defines and creates/updates a Couchbase Search index configured for vector search. Index creation in Couchbase is asynchronous; allow a short time after creation before querying, especially on larger datasets.
+- **Data Storage:** Vectors and metadata are stored together as fields within standard Couchbase documents in the specified Collection.
+  - The default field name for the vector embedding is `"embedding"`.
+  - The default field name for metadata is `"metadata"`.
+  - If `metadata` contains a `text` property, its value is also copied to a top-level `"content"` field in the document, which is indexed by the Search index created by this library.
+- **Upsert Independence:** The `upsert` operation adds/modifies documents directly in the Collection. It **does not depend on the Search index** existing at the time of upsert. You can insert data before or after creating the index. Couchbase allows multiple Search indexes over the same Collection data.
+- **Dimension Validation:**
+  - This library _attempts_ to track the dimension specified during the last `createIndex` call within the same `CouchbaseVector` instance. If tracked, it performs a basic length check during `upsert`.
+  - However, Couchbase itself **does not enforce vector dimensions at data ingest time**. Upserting a vector with a dimension different from what an index expects **will not cause an error during `upsert`**. Errors related to dimension mismatches will typically occur only during the `query` operation against that specific index.
+- **Asynchronous Operations & Consistency:** Be mindful of the asynchronous nature of index building and potential replication delays in Couchbase, especially in multi-node clusters. Add appropriate checks or delays in your application logic if immediate consistency after writes is required for subsequent queries.
+  - **Index Creation Delays:** After creating a vector search index, allow sufficient time (typically 1-5 seconds for small datasets, longer for larger ones) before querying against it. The delay needed depends on data volume, cluster resources, and replication settings.
+  - **Vector Insertion Processing:** When upserting large batches of vectors, the documents may not be immediately queryable. Consider implementing appropriate wait times or retry mechanisms when performing queries immediately after bulk inserts.
+  - **Production Considerations:** For production environments, implement a more robust polling mechanism to check index status rather than fixed timeouts.
+- **Current Limitations:**
+  - **Metadata Filtering:** The `filter` parameter in the `query` method is **not yet supported** by this library. Filtering must be done client-side after retrieving results or by using the Couchbase SDK's Search capabilities directly for more complex queries.
+  - **Returning Vectors:** The `includeVector: true` option in the `query` method is **not yet supported**. To retrieve the vector embedding, you must fetch the full document using its ID (returned in the query results) via the Couchbase SDK's Key-Value operations (`collection.get(id)`).
+  - **Index Count:** The `describeIndex` method currently **returns -1 for the count** of indexed documents. Use Couchbase tools (UI, CLI, SQL++ query on the collection, Search API) for accurate index statistics.
+
+## Related Links
+
+- [Couchbase Vector Search Documentation](https://docs.couchbase.com/cloud/vector-search/vector-search.html)
+- [Couchbase Node.js SDK Documentation](https://docs.couchbase.com/nodejs-sdk/current/hello-world/start-using-sdk.html)
+- [Couchbase Query Language (SQL++) for working with documents](https://docs.couchbase.com/server/current/n1ql/n1ql-language-reference/index.html)
+- [Couchbase Search Service API / Index Definition](https://docs.couchbase.com/cloud/search/search-index-params.html)
+
+---
+
+## 📢 Support Policy
+
+We truly appreciate your interest in this project!
+This project is **community-maintained**, which means it's **not officially supported** by our support team.
+
+If you need help, have found a bug, or want to contribute improvements, the best place to do that is right here — by [opening a GitHub issue](https://github.com/mastra-ai/mastra/issues) (Update this link to your project's issue tracker!).
+Our support portal is unable to assist with requests related to this project, so we kindly ask that all inquiries stay within GitHub.
+
+Your collaboration helps us all move forward together — thank you!

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

@@ -0,0 +1,39 @@
+import type { Collection } from 'couchbase';
+import type { CreateIndexParams } from '@mastra/core/vector';
+import type { IndexStats } from '@mastra/core/vector';
+import { MastraVector } 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';
+
+declare type CouchbaseMetric = 'cosine' | 'l2_norm' | 'dot_product';
+
+declare class CouchbaseVector extends MastraVector {
+    private clusterPromise;
+    private cluster;
+    private bucketName;
+    private collectionName;
+    private scopeName;
+    private collection;
+    private bucket;
+    private scope;
+    private vector_dimension;
+    constructor(cnn_string: string, username: string, password: string, bucketName: string, scopeName: string, collectionName: string);
+    getCollection(): Promise<Collection>;
+    createIndex(params: CreateIndexParams): Promise<void>;
+    upsert(params: UpsertVectorParams): Promise<string[]>;
+    query(params: QueryVectorParams): Promise<QueryResult[]>;
+    listIndexes(): Promise<string[]>;
+    describeIndex(indexName: string): Promise<IndexStats>;
+    deleteIndex(indexName: string): Promise<void>;
+}
+export { CouchbaseVector }
+export { CouchbaseVector as CouchbaseVector_alias_1 }
+
+declare const DISTANCE_MAPPING: Record<MastraMetric, CouchbaseMetric>;
+export { DISTANCE_MAPPING }
+export { DISTANCE_MAPPING as DISTANCE_MAPPING_alias_1 }
+
+declare type MastraMetric = 'cosine' | 'euclidean' | 'dotproduct';
+
+export { }

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

@@ -0,0 +1,39 @@
+import type { Collection } from 'couchbase';
+import type { CreateIndexParams } from '@mastra/core/vector';
+import type { IndexStats } from '@mastra/core/vector';
+import { MastraVector } 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';
+
+declare type CouchbaseMetric = 'cosine' | 'l2_norm' | 'dot_product';
+
+declare class CouchbaseVector extends MastraVector {
+    private clusterPromise;
+    private cluster;
+    private bucketName;
+    private collectionName;
+    private scopeName;
+    private collection;
+    private bucket;
+    private scope;
+    private vector_dimension;
+    constructor(cnn_string: string, username: string, password: string, bucketName: string, scopeName: string, collectionName: string);
+    getCollection(): Promise<Collection>;
+    createIndex(params: CreateIndexParams): Promise<void>;
+    upsert(params: UpsertVectorParams): Promise<string[]>;
+    query(params: QueryVectorParams): Promise<QueryResult[]>;
+    listIndexes(): Promise<string[]>;
+    describeIndex(indexName: string): Promise<IndexStats>;
+    deleteIndex(indexName: string): Promise<void>;
+}
+export { CouchbaseVector }
+export { CouchbaseVector as CouchbaseVector_alias_1 }
+
+declare const DISTANCE_MAPPING: Record<MastraMetric, CouchbaseMetric>;
+export { DISTANCE_MAPPING }
+export { DISTANCE_MAPPING as DISTANCE_MAPPING_alias_1 }
+
+declare type MastraMetric = 'cosine' | 'euclidean' | 'dotproduct';
+
+export { }

package/dist/index.cjs

@@ -0,0 +1,243 @@
+'use strict';
+
+var vector = require('@mastra/core/vector');
+var couchbase = require('couchbase');
+
+// src/vector/index.ts
+var DISTANCE_MAPPING = {
+  cosine: "cosine",
+  euclidean: "l2_norm",
+  dotproduct: "dot_product"
+};
+var CouchbaseVector = class extends vector.MastraVector {
+  clusterPromise;
+  cluster;
+  bucketName;
+  collectionName;
+  scopeName;
+  collection;
+  bucket;
+  scope;
+  vector_dimension;
+  constructor(cnn_string, username, password, bucketName, scopeName, collectionName) {
+    super();
+    const baseClusterPromise = couchbase.connect(cnn_string, {
+      username,
+      password,
+      configProfile: "wanDevelopment"
+    });
+    const telemetry = this.__getTelemetry();
+    this.clusterPromise = telemetry?.traceClass(baseClusterPromise, {
+      spanNamePrefix: "couchbase-vector",
+      attributes: {
+        "vector.type": "couchbase"
+      }
+    }) ?? baseClusterPromise;
+    this.cluster = null;
+    this.bucketName = bucketName;
+    this.collectionName = collectionName;
+    this.scopeName = scopeName;
+    this.collection = null;
+    this.bucket = null;
+    this.scope = null;
+    this.vector_dimension = null;
+  }
+  async getCollection() {
+    if (!this.cluster) {
+      this.cluster = await this.clusterPromise;
+    }
+    if (!this.collection) {
+      this.bucket = this.cluster.bucket(this.bucketName);
+      this.scope = this.bucket.scope(this.scopeName);
+      this.collection = this.scope.collection(this.collectionName);
+    }
+    return this.collection;
+  }
+  async createIndex(params) {
+    const { indexName, dimension, metric = "dotproduct" } = params;
+    await this.getCollection();
+    if (!Number.isInteger(dimension) || dimension <= 0) {
+      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
+          },
+          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
+        }
+      },
+      sourceUuid: "",
+      sourceParams: {},
+      sourceType: "gocbcore",
+      planParams: {
+        maxPartitionsPerPIndex: 64,
+        indexPartitions: 16,
+        numReplicas: 0
+      }
+    });
+    this.vector_dimension = dimension;
+  }
+  async upsert(params) {
+    const { vectors, metadata, ids } = params;
+    await this.getCollection();
+    if (!vectors || vectors.length === 0) {
+      throw new Error("No vectors provided");
+    }
+    if (this.vector_dimension) {
+      for (const vector of vectors) {
+        if (!vector || this.vector_dimension !== vector.length) {
+          throw new Error("Vector dimension mismatch");
+        }
+      }
+    }
+    const pointIds = ids || vectors.map(() => crypto.randomUUID());
+    const records = vectors.map((vector, i) => {
+      const metadataObj = metadata?.[i] || {};
+      const record = {
+        embedding: vector,
+        metadata: metadataObj
+      };
+      if (metadataObj.text) {
+        record.content = metadataObj.text;
+      }
+      return record;
+    });
+    const allPromises = [];
+    for (let i = 0; i < records.length; i++) {
+      allPromises.push(this.collection.upsert(pointIds[i], records[i]));
+    }
+    await Promise.all(allPromises);
+    return pointIds;
+  }
+  async query(params) {
+    const { indexName, queryVector, topK = 10, includeVector = false } = params;
+    await this.getCollection();
+    const index_stats = await this.describeIndex(indexName);
+    if (queryVector.length !== index_stats.dimension) {
+      throw new Error(`Query vector dimension mismatch. Expected ${index_stats.dimension}, got ${queryVector.length}`);
+    }
+    let request = couchbase.SearchRequest.create(
+      couchbase.VectorSearch.fromVectorQuery(couchbase.VectorQuery.create("embedding", queryVector).numCandidates(topK))
+    );
+    const results = await this.scope.search(indexName, request, {
+      fields: ["*"]
+    });
+    if (includeVector) {
+      throw new Error("Including vectors in search results is not yet supported by the Couchbase vector store");
+    }
+    const output = [];
+    for (const match of results.rows) {
+      const cleanedMetadata = {};
+      const fields = match.fields || {};
+      for (const key in fields) {
+        if (Object.prototype.hasOwnProperty.call(fields, key)) {
+          const newKey = key.startsWith("metadata.") ? key.substring("metadata.".length) : key;
+          cleanedMetadata[newKey] = fields[key];
+        }
+      }
+      output.push({
+        id: match.id,
+        score: match.score || 0,
+        metadata: cleanedMetadata
+        // Use the cleaned metadata object
+      });
+    }
+    return output;
+  }
+  async listIndexes() {
+    await this.getCollection();
+    const indexes = await this.scope.searchIndexes().getAllIndexes();
+    return indexes?.map((index) => index.name) || [];
+  }
+  async describeIndex(indexName) {
+    await this.getCollection();
+    if (!(await this.listIndexes()).includes(indexName)) {
+      throw new Error(`Index ${indexName} does not exist`);
+    }
+    const index = await this.scope.searchIndexes().getIndex(indexName);
+    const dimensions = index.params.mapping?.types?.[`${this.scopeName}.${this.collectionName}`]?.properties?.embedding?.fields?.[0]?.dims;
+    const count = -1;
+    const metric = index.params.mapping?.types?.[`${this.scopeName}.${this.collectionName}`]?.properties?.embedding?.fields?.[0]?.similarity;
+    return {
+      dimension: dimensions,
+      count,
+      metric: Object.keys(DISTANCE_MAPPING).find(
+        (key) => DISTANCE_MAPPING[key] === metric
+      )
+    };
+  }
+  async deleteIndex(indexName) {
+    await this.getCollection();
+    if (!(await this.listIndexes()).includes(indexName)) {
+      throw new Error(`Index ${indexName} does not exist`);
+    }
+    await this.scope.searchIndexes().dropIndex(indexName);
+    this.vector_dimension = null;
+  }
+};
+
+exports.CouchbaseVector = CouchbaseVector;
+exports.DISTANCE_MAPPING = DISTANCE_MAPPING;