Couchbase vector store

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

Requirements

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

Installation

npm

npm install @mastra/couchbase@latest

pnpm

pnpm add @mastra/couchbase@latest

Yarn

yarn add @mastra/couchbase@latest

Bun

bun add @mastra/couchbase@latest

Usage example

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,
})

Constructor options

id:

string

Unique identifier for this vector store instance

connectionString:

string

Couchbase connection string

username:

string

Couchbase username

password:

string

Couchbase password

bucketName:

string

Name of the Couchbase bucket to use

scopeName:

string

Name of the Couchbase scope to use

collectionName:

string

Name of the Couchbase collection to use

Methods

createIndex()

Creates a new vector index in Couchbase.

note

Index creation is asynchronous. After calling createIndex, allow time (typically 1 to 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:

string

Name of the index to create

dimension:

number

Vector dimension (must match your embedding model)

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= dotproduct

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.

indexName:

string

Name of the index to insert into

vectors:

number[][]

Array of embedding vectors

metadata?:

Record<string, any>[]

Metadata for each vector

ids?:

string[]

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 through the Couchbase SDK's Search capabilities. Retrieve the vector embedding by fetching the full document by ID with the Couchbase SDK.

indexName:

string

Name of the index to search in

queryVector:

number[]

Query vector to find similar vectors for

topK?:

number

= 10

Number of results to return

filter?:

Record<string, any>

Not supported. Filters passed here are ignored.

includeVector?:

boolean

= false

Not supported. Setting this to true throws an error.

describeIndex()

Returns information about the index.

indexName:

string

Name of the index to describe

Returns:

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

deleteIndex()

Deletes the Search index. Documents stored in the collection aren't deleted.

indexName:

string

Name of the index to delete

listIndexes()

Lists the names of all Search indexes in the configured scope.

Returns: Promise<string[]>

updateVector()

Updates a specific vector entry by its ID with new vector data and/or metadata. Filter-based updates aren't yet implemented for Couchbase.

indexName:

string

Name of the index containing the vector

id:

string

ID of the vector entry to update

update:

{ vector?: number[]; metadata?: Record<string, any>; }

Object containing the vector and/or metadata to update

deleteVector()

Deletes a single vector by its ID from the index.

indexName:

string

Name of the index containing the vector

id:

string

ID of the vector to delete

deleteVectors()

Deletes vectors by ID from the configured Couchbase collection. Pass a non-empty ids array to remove multiple documents. Missing IDs are ignored. Filter-based deletion isn't supported and throws a MastraError. Providing an empty ids array, both ids and filter, or neither, also throws.

await store.deleteVectors({ indexName: 'my_index', ids: ['vec_1', 'vec_2'] })

indexName:

string

Name of the index containing the vectors to delete

ids:

string[]

IDs of the vectors to delete (required for Couchbase)

filter?:

VectorFilter

Not supported for Couchbase. Passing a filter throws an error

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>
}

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 doesn't 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 builds a Search Index definition for documents in scopeName.collectionName. It indexes the embedding field as a vector and the content field as text. Each document stores its vector in embedding, with metadata kept in metadata. A text property within metadata is also copied to the top-level content field 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.
• Vector dimension is enforced at ingest only after createIndex() creates a new index on the same CouchbaseVector instance. Calling createIndex() for an index that already exists doesn't turn on the ingest check. When the check is on, upsert() and updateVector() throw on a dimension mismatch. query() always checks the query vector against the index dimension.
• deleteVectors() supports deletion by ID only. Metadata-filter deletion isn't supported.
• Vector insertion and index updates are eventually consistent. Strong consistency isn't guaranteed immediately after writes.

Related

• Metadata Filters