> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# DuckDB 向量儲存

DuckDB 儲存實作使用程序內分析資料庫 [DuckDB](https://duckdb.org/)，提供嵌入式高效能向量搜尋解決方案。它使用 VSS 擴充功能配合 HNSW 索引執行向量相似度搜尋，提供無需外部伺服器的輕量高效向量資料庫。

它是 `@mastra/duckdb` 套件的一部分，提供支援元資料篩選的高效向量相似度搜尋。

## 安裝

**npm**:

```bash
npm install @mastra/duckdb@latest
```

**pnpm**:

```bash
pnpm add @mastra/duckdb@latest
```

**Yarn**:

```bash
yarn add @mastra/duckdb@latest
```

**Bun**:

```bash
bun add @mastra/duckdb@latest
```

## 用法

```typescript
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`): 向量儲存實例的唯一識別符

**path** (`string`): 資料庫檔案路徑。記憶體內資料庫請使用 ':memory:'；如要持久儲存，請使用檔案路徑，例如 './vectors.duckdb'。 (Default: `':memory:'`)

**dimensions** (`number`): 向量嵌入的預設維度 (Default: `1536`)

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 相似度搜尋的預設距離度量 (Default: `cosine`)

## 方法

### `createIndex()`

建立新的向量集合，並可選擇加入 HNSW 索引，以進行快速近似最近鄰搜尋。

**indexName** (`string`): 要建立的索引名稱

**dimension** (`number`): 向量維度大小（必須與嵌入模型相符）

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 相似度搜尋所使用的距離度量 (Default: `cosine`)

### `upsert()`

在索引中加入或更新向量及其元資料。

**indexName** (`string`): 要插入資料的索引名稱

**vectors** (`number[][]`): 嵌入向量陣列

**metadata** (`Record<string, any>[]`): 每個向量的元資料

**ids** (`string[]`): 可選的向量 ID（如未提供則自動產生 UUID）

### `query()`

搜尋相似向量，並可選擇使用元資料篩選。

**indexName** (`string`): 要搜尋的索引名稱

**queryVector** (`number[]`): 用來尋找相似向量的查詢向量

**topK** (`number`): 要傳回的結果數目 (Default: `10`)

**filter** (`Filter`): 使用類似 MongoDB 查詢語法的元資料篩選條件

**includeVector** (`boolean`): 是否在結果中包含向量資料 (Default: `false`)

### `describeIndex()`

取得索引的資料。

**indexName** (`string`): 要取得資料的索引名稱

傳回：

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

### `deleteIndex()`

刪除索引及其所有資料。

**indexName** (`string`): 要刪除的索引名稱

### `listIndexes()`

列出資料庫中的所有向量索引。

傳回：`Promise<string[]>`

### `updateVector()`

按 ID 或元資料篩選條件更新單一向量。必須提供 `id` 或 `filter`，但不可同時提供兩者。

**indexName** (`string`): 包含該向量的索引名稱

**id** (`string`): 要更新的向量項目 ID（與 filter 互斥）

**filter** (`Record<string, any>`): 用來識別待更新向量的元資料篩選條件（與 id 互斥）

**update** (`object`): 包含向量及／或元資料的更新資料

**update.vector** (`number[]`): 要更新的新向量資料

**update.metadata** (`Record<string, any>`): 要更新的新元資料

### `deleteVector()`

按 ID 從索引刪除指定的向量項目。

**indexName** (`string`): 包含該向量的索引名稱

**id** (`string`): 要刪除的向量項目 ID

### `deleteVectors()`

按 ID 或元資料篩選條件刪除多個向量。必須提供 `ids` 或 `filter`，但不可同時提供兩者。

**indexName** (`string`): 包含待刪除向量的索引名稱

**ids** (`string[]`): 待刪除的向量 ID 陣列（與 filter 互斥）

**filter** (`Record<string, any>`): 用來識別待刪除向量的元資料篩選條件（與 ids 互斥）

### `close()`

關閉資料庫連線並釋放資源。

```typescript
await store.close()
```

## 回應類型

查詢結果會以下列格式傳回：

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

## 篩選運算子

DuckDB 向量儲存支援類似 MongoDB 的篩選運算子：

| 類別 | 運算子                                        |
| -- | ------------------------------------------ |
| 比較 | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte` |
| 邏輯 | `$and`, `$or`, `$not`, `$nor`              |
| 陣列 | `$in`, `$nin`                              |
| 元素 | `$exists`                                  |
| 文字 | `$contains`                                |

### 篩選範例

```typescript
// 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 = 最相似） | 文字嵌入、正規化向量 |
| `euclidean`  | L2 距離 | 0–∞（0 = 最相似） | 圖像嵌入、空間資料  |
| `dotproduct` | 內積    | 數值越高越相似      | 向量大小會影響結果時 |

## 錯誤處理

此向量儲存會針對不同失敗情況擲回特定錯誤：

```typescript
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)
  }
}
```

常見錯誤情況包括：

- 索引名稱格式無效
- 找不到索引／資料表
- 查詢向量與索引的維度不相符
- 刪除／更新操作中的 filter 或 ids 陣列為空
- 違反互斥條件（同時提供 `id` 與 `filter`）

## 使用案例

### 嵌入式語意搜尋

建構支援離線操作的 AI 應用程式，其語意搜尋完全在程序內執行：

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

### 本機 RAG 管線

在本機處理敏感文件，無需將資料傳送至雲端向量資料庫：

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

### 開發與測試

無需基礎設施即可快速製作向量搜尋功能原型：

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

## 相關內容

- [元資料篩選器](https://mastra.zisheng.pro/zh-HK/reference/rag/metadata-filters)
- [DuckDB 文件](https://duckdb.org/docs/)