DuckDB vector store

DuckDB ストレージ実装は、インプロセス分析データベースの DuckDB を使用した、組み込み型の高性能ベクトル検索ソリューションを提供します。VSS 拡張機能による HNSW インデックスを使用したベクトル類似度検索に対応し、外部サーバーを必要としない軽量で効率的なベクトルデータベースとして利用できます。

@mastra/duckdb パッケージに含まれ、メタデータフィルタリングに対応した効率的なベクトル類似度検索を提供します。

インストール

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

path?:

string

= ':memory:'

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

dimensions?:

number

= 1536

ベクトル埋め込みのデフォルト次元数

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

類似度検索のデフォルト距離指標

メソッド

createIndex()

高速な近似最近傍探索に使用できる HNSW インデックスを備えた、新しいベクトルコレクションを作成します。HNSW インデックスは省略可能です。

indexName:

string

作成するインデックスの名前

dimension:

number

ベクトルの次元数（埋め込みモデルと一致させる必要があります）

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

類似度検索の距離指標

upsert()

インデックス内のベクトルとそのメタデータを追加または更新します。

indexName:

string

挿入先のインデックス名

vectors:

number[][]

埋め込みベクトルの配列

metadata?:

Record<string, any>[]

各ベクトルのメタデータ

ids?:

string[]

省略可能なベクトル ID（未指定の場合は UUID が自動生成されます）

query()

省略可能なメタデータフィルターを使用して、類似するベクトルを検索します。

indexName:

string

検索対象のインデックス名

queryVector:

number[]

類似ベクトルを検索するクエリベクトル

topK?:

number

= 10

返す結果の数

filter?:

Filter

MongoDB に似たクエリ構文を使用するメタデータフィルター

includeVector?:

boolean

= false

結果にベクトルデータを含めるかどうか

describeIndex()

インデックスの情報を取得します。

indexName:

string

詳細を取得するインデックスの名前

戻り値:

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

データベース接続を閉じ、リソースを解放します。

await store.close()

レスポンス型

クエリ結果は次の形式で返されます。

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

フィルターの例

// 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 は障害の種類に応じたエラーをスローします。

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 アプリケーションを構築します。

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

ローカル RAG パイプライン

クラウドのベクトルデータベースにデータを送信せず、機密ドキュメントをローカルで処理します。

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

開発とテスト

インフラストラクチャを用意せずに、ベクトル検索機能をすばやく試作します。

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

関連情報

• メタデータフィルター
• DuckDB ドキュメント