Couchbase Vector Store

The CouchbaseVector class provides vector search using Couchbase Vector Search . It enables efficient similarity search and metadata filtering within your Couchbase collections.

Requirements

• Couchbase Server 7.6.4+ or a compatible Capella cluster
• Search Service enabled on your Couchbase deployment

Installation

npm install @mastra/couchbase

Usage Example

import { CouchbaseVector } from '@mastra/couchbase';
 
const store = new CouchbaseVector({
  connectionString: process.env.COUCHBASE_CONNECTION_STRING,
  username: process.env.COUCHBASE_USERNAME,
  password: process.env.COUCHBASE_PASSWORD,
  bucketName: process.env.COUCHBASE_BUCKET,
  scopeName: process.env.COUCHBASE_SCOPE,
  collectionName: process.env.COUCHBASE_COLLECTION,
});

Constructor Options

Methods

createIndex()

Creates a new vector index in Couchbase.

Note: Index creation is asynchronous. After calling createIndex, allow time (typically 1–5 seconds for small datasets, longer for large ones) before querying. For production, implement polling to check index status rather than using fixed delays.

upsert()

Adds or updates vectors and their metadata in the collection.

Note: You can upsert data before or after creating the index. The upsert method does not require the index to exist. Couchbase allows multiple Search indexes over the same collection.

query()

Searches for similar vectors.

Warning: The filter and includeVector parameters are not currently supported. Filtering must be performed client-side after retrieving results, or by using the Couchbase SDK’s Search capabilities directly. To retrieve the vector embedding, fetch the full document by ID using the Couchbase SDK.

describeIndex()

Returns information about the index.

Returns:

interface IndexStats {
  dimension: number;
  count: number;
  metric: "cosine" | "euclidean" | "dotproduct";
}

deleteIndex()

Deletes an index and all its data.

listIndexes()

Lists all vector indexes in the Couchbase bucket.

Returns: Promise<string[]>

updateVector()

Updates a specific vector entry by its ID with new vector data and/or metadata.

deleteVector()

Deletes a specific vector entry from an index by its ID.

disconnect()

Closes the Couchbase client connection. Should be called when done using the store.

Response Types

Query results are returned in this format:

interface QueryResult {
  id: string;
  score: number;
  metadata: Record<string, any>;
  vector?: number[]; // Only included if includeVector is true
}

Error Handling

The store throws typed errors that can be caught:

try {
  await store.query({
    indexName: "my_index",
    queryVector: queryVector,
  });
} catch (error) {
  // Handle specific error cases
  if (error.message.includes("Invalid index name")) {
    console.error(
      "Index name must start with a letter or underscore and contain only valid characters."
    );
  } else if (error.message.includes("Index not found")) {
    console.error("The specified index does not exist");
  } else {
    console.error("Vector store error:", error.message);
  }
}

Notes

• Index Deletion Caveat: Deleting a Search index does NOT delete the vectors/documents in the associated Couchbase collection. Data remains unless explicitly removed.
• Required Permissions: The Couchbase user must have permissions to connect, read/write documents in the target collection (kv role), and manage Search Indexes (search_admin role on the relevant bucket/scope).
• Index Definition Details & Document Structure: The createIndex method constructs a Search Index definition that indexes the embedding field (as type vector) and the content field (as type text), targeting documents within the specified scopeName.collectionName. Each document stores the vector in the embedding field and metadata in the metadata field. If metadata contains a text property, its value is also copied to a top-level content field, which is indexed for text search.
• Replication & Durability: Consider using Couchbase’s built-in replication and persistence features for data durability. Monitor index statistics regularly to ensure efficient search.

Limitations

• Index creation delays may impact immediate querying after creation.
• No hard enforcement of vector dimension at ingest time (dimension mismatches will error at query time).
• Vector insertion and index updates are eventually consistent; strong consistency is not guaranteed immediately after writes.

Related

• Metadata Filters