DuckDB Vector 存储

DuckDB storage 实现使用进程内分析数据库 DuckDB 提供嵌入式高性能 Vector 搜索解决方案。它使用 VSS extension，通过 HNSW 索引进行 Vector 相似度搜索，提供轻量、高效且无需外部服务器的 Vector 数据库。

它是 @mastra/duckdb 包的一部分，提供高效的 Vector 相似度搜索和元数据过滤。

安装

npm

npm install @mastra/duckdb@latest

pnpm

pnpm add @mastra/duckdb@latest

Yarn

yarn add @mastra/duckdb@latest

Bun

bun add @mastra/duckdb@latest

用法

import { DuckDBVector } from "@mastra/duckdb";

// Create a new vector store instance
const store = new DuckDBVector({
  id: "duckdb-vector",
  path: ":memory:", // or './vectors.duckdb' for file persistence
});

// Create an index
await store.createIndex({
  indexName: "myCollection",
  dimension: 1536,
  metric: "cosine",
});

// Add vectors with metadata
const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
const metadata = [
  { text: "first document", category: "A" },
  { text: "second document", category: "B" },
];
await store.upsert({
  indexName: "myCollection",
  vectors,
  metadata,
});

// Query similar vectors
const queryVector = [0.1, 0.2, ...];
const results = await store.query({
  indexName: "myCollection",
  queryVector,
  topK: 10,
  filter: { category: "A" },
});

// Clean up
await store.close();

构造函数选项

id:

string

Vector 存储实例的唯一标识符

path?:

string

= ':memory:'

数据库文件路径。使用 ':memory:' 创建内存数据库，或使用 './vectors.duckdb' 等文件路径实现持久化。

dimensions?:

number

= 1536

Vector embedding 的默认维度

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

相似度搜索的默认距离度量

方法

createIndex()

创建新的 Vector collection，并可选择添加 HNSW 索引以进行快速近似最近邻搜索。

indexName:

string

要创建的索引名称

dimension:

number

Vector 维度大小（必须与 embedding 模型匹配）

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

相似度搜索的距离度量

upsert()

在索引中添加或更新 Vector 及其元数据。

indexName:

string

要插入数据的索引名称

vectors:

number[][]

embedding Vector 数组

metadata?:

Record<string, any>[]

每个 Vector 的元数据

ids?:

string[]

可选的 Vector ID（未提供时自动生成 UUID）

query()

搜索相似 Vector，并可选择使用元数据过滤。

indexName:

string

要在其中搜索的索引名称

queryVector:

number[]

用于查找相似 Vector 的查询 Vector

topK?:

number

= 10

要返回的结果数量

filter?:

Filter

使用类似 MongoDB 查询语法的元数据过滤条件

includeVector?:

boolean

= false

是否在结果中包含 Vector 数据

describeIndex()

获取索引相关信息。

indexName:

string

要描述的索引名称

返回：

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

deleteIndex()

删除索引及其所有数据。

indexName:

string

要删除的索引名称

listIndexes()

列出数据库中的所有 Vector 索引。

返回：Promise<string[]>

updateVector()

通过 ID 或元数据过滤条件更新单个 Vector。必须提供 id 或 filter，但不能同时提供二者。

indexName:

string

包含该 Vector 的索引名称

id?:

string

要更新的 Vector 条目 ID（与 filter 互斥）

filter?:

Record<string, any>

用于识别要更新 Vector 的元数据过滤条件（与 id 互斥）

update:

object

包含 Vector 和/或元数据的更新数据

update.vector?:

number[]

要更新的新 Vector 数据

update.metadata?:

Record<string, any>

要更新的新元数据

deleteVector()

根据 ID 从索引中删除特定 Vector 条目。

indexName:

string

包含该 Vector 的索引名称

id:

string

要删除的 Vector 条目 ID

deleteVectors()

通过 ID 或元数据过滤条件删除多个 Vector。必须提供 ids 或 filter，但不能同时提供二者。

indexName:

string

包含要删除 Vector 的索引名称

ids?:

string[]

要删除的 Vector ID 数组（与 filter 互斥）

filter?:

Record<string, any>

用于识别要删除 Vector 的元数据过滤条件（与 ids 互斥）

close()

关闭数据库连接并释放资源。

await store.close()

响应类型

查询结果按以下格式返回：

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

过滤运算符

DuckDB Vector 存储支持类似 MongoDB 的过滤运算符：

类别	运算符
比较	$eq, $ne, $gt, $gte, $lt, $lte
逻辑	$and, $or, $not, $nor
数组	$in, $nin
元素	$exists
文本	$contains

过滤示例

// Allegato operators
const results = await store.query({
  indexName: "docs",
  queryVector: [...],
  filter: {
    $and: [
      { category: "electronics" },
      { price: { $gte: 100, $lte: 500 } },
    ],
  },
});

// Nested field access
const results = await store.query({
  indexName: "docs",
  queryVector: [...],
  filter: { "user.profile.tier": "premium" },
});

距离度量

度量	描述	分数含义	最适合
cosine	余弦相似度	0-1（1 = 最相似）	文本 embedding、归一化 Vector
euclidean	L2 距离	0-∞（0 = 最相似）	图像 embedding、空间数据
dotproduct	内积	越高越相似	Vector 大小会影响结果的场景

错误处理

针对不同的失败情况，该存储会抛出特定错误：

try {
  await store.query({
    indexName: 'my-collection',
    queryVector: queryVector,
  })
} catch (error) {
  if (error.message.includes('not found')) {
    console.error('The specified index does not exist')
  } else if (error.message.includes('Invalid identifier')) {
    console.error('Index name contains invalid characters')
  } else {
    console.error('Vector store error:', error.message)
  }
}

常见错误情况包括：

• 索引名称格式无效
• 找不到索引/表
• 查询 Vector 与索引的维度不匹配
• 删除/更新操作中的 filter 或 ids 数组为空
• 违反互斥约束（同时提供 id 和 filter）

使用场景

嵌入式语义搜索

构建支持离线运行的 AI 应用，完全在进程内执行语义搜索：

const store = new DuckDBVector({
  id: 'offline-search',
  path: './search.duckdb',
})

本地 RAG pipeline

在本地处理敏感文档，无需将数据发送到云端 Vector 数据库：

const store = new DuckDBVector({
  id: 'private-rag',
  path: './confidential.duckdb',
  dimensions: 1536,
})

开发和测试

无需任何基础设施即可快速构建 Vector 搜索功能原型：

const store = new DuckDBVector({
  id: 'dev-store',
  path: ':memory:', // Fast in-memory for tests
})

相关内容

• 元数据过滤器
• DuckDB 文档