docs/src/content/en/reference/vectors/couchbase.mdx
The CouchbaseVector class provides vector search using Couchbase Vector Search. It enables efficient similarity search and metadata filtering within your Couchbase collections.
npm install @mastra/couchbase@latest
import { CouchbaseVector } from '@mastra/couchbase'
const store = new CouchbaseVector({
id: 'couchbase-vector',
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,
})
<PropertiesTable content={[ { name: 'id', type: 'string', description: 'Unique identifier for this vector store instance', }, { name: 'connectionString', type: 'string', description: 'Couchbase connection string', }, { name: 'username', type: 'string', description: 'Couchbase username', }, { name: 'password', type: 'string', description: 'Couchbase password', }, { name: 'bucketName', type: 'string', description: 'Name of the Couchbase bucket to use', }, { name: 'scopeName', type: 'string', description: 'Name of the Couchbase scope to use', }, { name: 'collectionName', type: 'string', description: 'Name of the Couchbase collection to use', }, { name: 'options', type: 'CouchbaseClientOptions', isOptional: true, description: 'Optional Couchbase client options', }, ]} />
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.
:::
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to create', }, { name: 'dimension', type: 'number', description: 'Vector dimension (must match your embedding model)', }, { name: 'metric', type: "'cosine' | 'euclidean' | 'dotproduct'", isOptional: true, defaultValue: 'cosine', description: 'Distance metric for similarity search', }, ]} />
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 doesn't require the index to exist. Couchbase allows multiple Search indexes over the same collection.
:::
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to insert into', }, { name: 'vectors', type: 'number[][]', description: 'Array of embedding vectors', }, { name: 'metadata', type: 'Record<string, any>[]', isOptional: true, description: 'Metadata for each vector', }, { name: 'ids', type: 'string[]', isOptional: true, description: 'Optional vector IDs (auto-generated if not provided)', }, ]} />
query()Searches for similar vectors.
:::warning
The filter and includeVector parameters aren't 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.
:::
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to search in', }, { name: 'queryVector', type: 'number[]', description: 'Query vector to find similar vectors for', }, { name: 'topK', type: 'number', isOptional: true, defaultValue: '10', description: 'Number of results to return', }, { name: 'filter', type: 'Record<string, any>', isOptional: true, description: 'Metadata filters', }, { name: 'includeVector', type: 'boolean', isOptional: true, defaultValue: 'false', description: 'Whether to include vector data in results', }, { name: 'minScore', type: 'number', isOptional: true, defaultValue: '0', description: 'Minimum similarity score threshold', }, ]} />
describeIndex()Returns information about the index.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to describe', }, ]} />
Returns:
interface IndexStats {
dimension: number
count: number
metric: 'cosine' | 'euclidean' | 'dotproduct'
}
deleteIndex()Deletes an index and all its data.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index to delete', }, ]} />
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. Note: Filter-based updates aren't yet implemented for Couchbase.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index containing the vector', }, { name: 'id', type: 'string', description: 'ID of the vector entry to update', }, { name: 'update', type: '{ vector?: number[]; metadata?: Record<string, any>; }', description: 'Object containing the vector and/or metadata to update', }, ]} />
deleteVector()Deletes a single vector by its ID from the index.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index containing the vector', }, { name: 'id', type: 'string', description: 'ID of the vector to delete', }, ]} />
deleteVectors()Deletes multiple vectors by their IDs. Note: Filter-based deletion isn't yet implemented for Couchbase.
<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the index containing the vectors to delete', }, { name: 'ids', type: 'string[]', description: 'Array of vector IDs to delete', }, ]} />
disconnect()Closes the Couchbase client connection. Should be called when done using the store.
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
}
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)
}
}
kv role), and manage Search Indexes (search_admin role on the relevant bucket/scope).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.