Couchbase 向量存储

🌐 Couchbase Vector Store

CouchbaseVector 类提供使用 Couchbase 向量搜索 的向量搜索功能。它使你能够在 Couchbase 集合中进行高效的相似性搜索和元数据过滤。

🌐 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+ 或兼容的 Capella 集群
• 搜索服务已启用 在你的 Couchbase 部署中

安装

🌐 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

options?:

CouchbaseClientOptions

Optional Couchbase client options

方法

🌐 Methods

createIndex()

在 Couchbase 中创建一个新的向量索引。

🌐 Creates a new vector index in Couchbase.

注意： 索引创建是异步的。在调用 createIndex 之后，请留出时间（小型数据集通常为 1–5 秒，大型数据集可能更长）再进行查询。在生产环境中，应通过轮询来检查索引状态，而不是使用固定延时。

indexName:

string

Name of the index to create

dimension:

number

Vector dimension (must match your embedding model)

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

Distance metric for similarity search

upsert()

在集合中添加或更新向量及其元数据。

🌐 Adds or updates vectors and their metadata in the collection.

注意： 你可以在创建索引之前或之后进行数据的插入或更新。upsert 方法不要求索引必须存在。Couchbase 允许在同一个集合上创建多个搜索索引。

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.

警告： 当前不支持 filter 和 includeVector 参数。必须在获取结果后在客户端进行过滤，或者直接使用 Couchbase SDK 的搜索功能。要获取向量嵌入，请使用 Couchbase SDK 通过 ID 获取完整文档。

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>

Metadata filters

includeVector?:

boolean

= false

Whether to include vector data in results

minScore?:

number

= 0

Minimum similarity score threshold

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 an index and all its data.

indexName:

string

Name of the index to delete

listIndexes()

列出 Couchbase 桶中的所有向量索引。

🌐 Lists all vector indexes in the Couchbase bucket.

返回：Promise<string[]>

🌐 Returns: Promise<string[]>

updateVector()

通过其 ID 使用新的向量数据和/或元数据更新特定向量条目。**注意：**基于过滤器的更新尚未在 Couchbase 中实现。

🌐 Updates a specific vector entry by its ID with new vector data and/or metadata. Note: Filter-based updates are not 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()

根据 ID 从索引中删除单个向量。

🌐 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()

通过其 ID 删除多个向量。**注意：**基于过滤器的删除尚未在 Couchbase 中实现。

🌐 Deletes multiple vectors by their IDs. Note: Filter-based deletion is not yet implemented for Couchbase.

indexName:

string

Name of the index containing the vectors to delete

ids:

string[]

Array of vector IDs to delete

disconnect()

关闭 Couchbase 客户端连接。使用完存储后应调用此方法。

🌐 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

• 索引删除注意事项： 删除搜索索引不会删除关联 Couchbase 集合中的向量/文档。除非明确删除，数据将保留。
• 所需权限： Couchbase 用户必须具有连接目标集合的权限、读写文档的权限（目标集合 kv 角色），以及管理搜索索引的权限（相关 bucket/scope 的 search_admin 角色）。
• 索引定义细节及文档结构： “createIndex”方法构建了一个搜索索引定义，索引“embedding”字段（类型为“vector”）和“content”字段（类型为“text”），目标是指定“scopeName.collectionName”范围内的文档。每个文档将向量存储在“embedding”字段，元数据存储在“metadata”字段。如果“metadata”包含“text”属性，其值也会复制到顶层的“content”字段，用于文本搜索索引。
• 复制与持久性： 建议使用 Couchbase 内置的复制和持久化功能来保证数据的持久性。定期监控索引统计信息，以确保搜索效率。

限制

🌐 Limitations

• 索引创建延迟可能会影响创建后的即时查询。
• 在数据导入时不会严格强制向量维度（维度不匹配将在查询时出错）。
• 向量插入和索引更新最终是一致的；写入后不会立即保证强一致性。

相关

🌐 Related

• 元数据过滤器