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

# DuckDB vector store

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`): vector store インスタンスの一意の識別子

**path** (`string`): データベースファイルのパス。インメモリデータベースには ':memory:'、永続化する場合は './vectors.duckdb' などのファイルパスを使用します。 (Default: `':memory:'`)

**dimensions** (`number`): ベクトル埋め込みのデフォルト次元数 (Default: `1536`)

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 類似度検索のデフォルト距離指標 (Default: `cosine`)

## メソッド

### `createIndex()`

高速な近似最近傍探索に使用できる HNSW インデックスを備えた、新しいベクトルコレクションを作成します。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 vector store は、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` | 内積      | 大きいほど類似      | ベクトルの大きさが重要な場合     |

## エラー処理

store は障害の種類に応じたエラーをスローします。

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

一般的なエラーには次のものがあります。

- インデックス名の形式が無効
- インデックスまたはテーブルが見つからない
- クエリベクトルとインデックスの次元数が一致しない
- 削除または更新操作で、フィルターまたは ID の配列が空
- 相互排他違反（`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/ja/reference/rag/metadata-filters)
- [DuckDB ドキュメント](https://duckdb.org/docs/)