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
connectionString:
username:
password:
bucketName:
scopeName:
collectionName:
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.
indexName:
dimension:
metric?:
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.
indexName:
vectors:
metadata?:
ids?:
query()
Searches for similar vectors.
Warning: The
filter
andincludeVector
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.
indexName:
queryVector:
topK?:
filter?:
includeVector?:
minScore?:
describeIndex()
Returns information about the index.
indexName:
Returns:
interface IndexStats {
dimension: number;
count: number;
metric: "cosine" | "euclidean" | "dotproduct";
}
deleteIndex()
Deletes an index and all its data.
indexName:
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.
indexName:
id:
update:
update.vector?:
update.metadata?:
deleteVector()
Deletes a specific vector entry from an index by its ID.
indexName:
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 theembedding
field (as typevector
) and thecontent
field (as typetext
), targeting documents within the specifiedscopeName.collectionName
. Each document stores the vector in theembedding
field and metadata in themetadata
field. Ifmetadata
contains atext
property, its value is also copied to a top-levelcontent
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.