Convex vector store

ConvexVector クラスは、Convex を使用したベクトルストレージと類似度検索を提供します。埋め込みを Convex 内に保存し、Mastra アダプターでコサイン類似度検索を実行します。

開発規模の検索

ConvexVector は、Mastra のストレージハンドラーを介して一致するベクトルを読み込み、JavaScript でフィルタリングし、コサイン類似度を計算して結果を並べ替え、上位の一致を返します。ローカル開発、テスト、小規模なデータセットに使用してください。

Convex で本番環境向けのベクトル検索を行うには、ConvexNativeVector を使用してください。Convex ネイティブの vectorSearch API を使用するため、デプロイ済みの Convex ベクトルインデックスと Convex action が必要です。

インストール

npm

npm install @mastra/convex@latest

pnpm

pnpm add @mastra/convex@latest

Yarn

yarn add @mastra/convex@latest

Bun

bun add @mastra/convex@latest

Convex のセットアップ

ConvexVector を使用する前に、Convex スキーマとストレージハンドラーをセットアップする必要があります。手順は Convex ストレージのセットアップを参照してください。

コンストラクターオプション

deploymentUrl:

string

Convex のデプロイ URL（例: https://your-project.convex.cloud）

adminAuthToken:

string

Convex 管理者認証トークン

storageFunction?:

string

= mastra/storage:handle

ストレージ mutation 関数へのパス

コンストラクターの例

基本設定

import { ConvexVector } from '@mastra/convex'

const vectorStore = new ConvexVector({
  id: 'convex-vectors',
  deploymentUrl: 'https://your-project.convex.cloud',
  adminAuthToken: 'your-admin-token',
})

Convex ネイティブベクトル検索

本番環境のベクトルワークロードには ConvexNativeVector を使用します。専用の Convex テーブルにベクトルを保存し、スキーマで定義された Convex ベクトルインデックスを検索します。

convex/schema.ts で、Mastra のベクトルインデックスごとに専用テーブルを定義します。

convex/schema.ts

import { defineSchema } from 'convex/server'
import { defineMastraNativeVectorTable } from '@mastra/convex/schema'

export default defineSchema({
  docs_vectors: defineMastraNativeVectorTable({
    dimensions: 1536,
  }),
})

convex/mastra/nativeVector.ts で、ネイティブベクトルハンドラーをエクスポートします。

convex/mastra/nativeVector.ts

import {
  mastraNativeVectorAction,
  mastraNativeVectorMutation,
  mastraNativeVectorQuery,
} from '@mastra/convex/server'

export const query = mastraNativeVectorAction
export const read = mastraNativeVectorQuery
export const write = mastraNativeVectorMutation

Mastra アプリで、デプロイ済みのテーブルとベクトルインデックスを指定して ConvexNativeVector を設定します。

src/mastra/index.ts

import { ConvexNativeVector } from '@mastra/convex'

const vectorStore = new ConvexNativeVector({
  id: 'convex-native-vectors',
  deploymentUrl: process.env.CONVEX_URL!,
  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
  indexes: {
    docs: {
      tableName: 'docs_vectors',
      vectorIndexName: 'by_embedding',
      dimension: 1536,
    },
  },
})

const results = await vectorStore.query({
  indexName: 'docs',
  queryVector: embedding,
  topK: 10,
})

ネイティブフィルターを使用するには、Convex スキーマでフィルターフィールドを宣言します。ネイティブベクトルハンドラーは、ベクトルの書き込み時に一致するメタデータフィールドをドキュメントのトップレベルフィールドへコピーします。

convex/schema.ts

import { defineSchema, defineTable } from 'convex/server'
import { v } from 'convex/values'

export default defineSchema({
  docs_vectors: defineTable({
    id: v.string(),
    embedding: v.array(v.float64()),
    metadata: v.optional(v.any()),
    tenantId: v.string(),
  })
    .index('by_record_id', ['id'])
    .vectorIndex('by_embedding', {
      vectorField: 'embedding',
      dimensions: 1536,
      filterFields: ['tenantId'],
    }),
})

src/mastra/index.ts

const vectorStore = new ConvexNativeVector({
  id: 'convex-native-vectors',
  deploymentUrl: process.env.CONVEX_URL!,
  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
  indexes: {
    docs: {
      tableName: 'docs_vectors',
      dimension: 1536,
      filterFields: ['tenantId'],
    },
  },
})

await vectorStore.upsert({
  indexName: 'docs',
  ids: ['chunk-1'],
  vectors: [embedding],
  metadata: [{ tenantId: 'acme', text: 'Account setup guide' }],
})

const results = await vectorStore.query({
  indexName: 'docs',
  queryVector: embedding,
  filter: { tenantId: 'acme' },
})

ConvexNativeVector は、1 つの等価フィールド、または等価フィールドを指定した $or という Convex ネイティブのベクトルフィルター形式に対応しています。メタデータのみのクエリ、フィルターベースの更新、フィルターベースの削除には対応していません。更新と削除にはベクトル ID を使用してください。

カスタムストレージ関数

const vectorStore = new ConvexVector({
  id: 'convex-vectors',
  deploymentUrl: 'https://your-project.convex.cloud',
  adminAuthToken: 'your-admin-token',
  storageFunction: 'custom/path:handler',
})

メソッド

createIndex()

indexName:

string

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

dimension:

number

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

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

類似度検索の距離指標（現在は cosine のみ対応）

await vectorStore.createIndex({
  indexName: 'my_vectors',
  dimension: 1536,
})

upsert()

indexName:

string

ベクトルの upsert 先となるインデックス名

vectors:

number[][]

埋め込みベクトルの配列

metadata?:

Record<string, any>[]

各ベクトルのメタデータ

ids?:

string[]

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

await vectorStore.upsert({
  indexName: "my_vectors",
  vectors: [[0.1, 0.2, 0.3, ...]],
  metadata: [{ label: "example" }],
  ids: ["vec-1"],
});

query()

indexName:

string

クエリ対象のインデックス名

queryVector:

number[]

クエリベクトル

topK?:

number

= 10

返す結果の数

filter?:

Record<string, any>

メタデータフィルター

includeVector?:

boolean

= false

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

const results = await vectorStore.query({
  indexName: "my_vectors",
  queryVector: [0.1, 0.2, 0.3, ...],
  topK: 5,
  filter: { category: "documents" },
});

listIndexes()

インデックス名を文字列の配列として返します。

const indexes = await vectorStore.listIndexes()
// ["my_vectors", "embeddings", ...]

describeIndex()

indexName:

string

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

戻り値:

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

deleteIndex()

indexName:

string

削除するインデックスの名前

インデックスとそのすべてのベクトルを削除します。

await vectorStore.deleteIndex({ indexName: 'my_vectors' })

updateVector()

ID またはメタデータフィルターで単一のベクトルを更新します。id と filter のどちらか一方のみを指定する必要があります。

indexName:

string

ベクトルを含むインデックスの名前

id?:

string

更新するベクトルの ID（filter とは同時に指定できません）

filter?:

Record<string, any>

更新するベクトルを特定するメタデータフィルター（id とは同時に指定できません）

update:

{ vector?: number[]; metadata?: Record<string, any>; }

更新するベクトルやメタデータを含むオブジェクト

// Update by ID
await vectorStore.updateVector({
  indexName: 'my_vectors',
  id: 'vector123',
  update: {
    vector: [0.1, 0.2, 0.3],
    metadata: { label: 'updated' },
  },
})

// Update by filter
await vectorStore.updateVector({
  indexName: 'my_vectors',
  filter: { category: 'product' },
  update: {
    metadata: { status: 'reviewed' },
  },
})

deleteVector()

indexName:

string

ベクトルを含むインデックスの名前

id:

string

削除するベクトルの ID

await vectorStore.deleteVector({ indexName: 'my_vectors', id: 'vector123' })

deleteVectors()

ID またはメタデータフィルターで複数のベクトルを削除します。ids と filter のどちらか一方のみを指定する必要があります。

indexName:

string

削除するベクトルを含むインデックスの名前

ids?:

string[]

削除するベクトル ID の配列（filter とは同時に指定できません）

filter?:

Record<string, any>

削除するベクトルを特定するメタデータフィルター（ids とは同時に指定できません）

// Delete by IDs
await vectorStore.deleteVectors({
  indexName: 'my_vectors',
  ids: ['vec1', 'vec2', 'vec3'],
})

// Delete by filter
await vectorStore.deleteVectors({
  indexName: 'my_vectors',
  filter: { status: 'archived' },
})

レスポンス型

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

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

メタデータフィルタリング

ConvexVector は演算子を使用したメタデータフィルタリングに対応しています。ベクトルを Convex から読み込んだ後、アダプターがこれらのフィルターを適用します。

// Simple equality
const results = await vectorStore.query({
  indexName: 'my_vectors',
  queryVector: embedding,
  filter: { category: 'documents' },
})

// Comparison operators
const results = await vectorStore.query({
  indexName: 'my_vectors',
  queryVector: embedding,
  filter: {
    price: { $gt: 100 },
    status: { $in: ['active', 'pending'] },
  },
})

// Logical operators
const results = await vectorStore.query({
  indexName: 'my_vectors',
  queryVector: embedding,
  filter: {
    $and: [{ category: 'electronics' }, { price: { $lte: 500 } }],
  },
})

対応するフィルター演算子

演算子	説明
$eq	等しい
$ne	等しくない
$gt	より大きい
$gte	以上
$lt	より小さい
$lte	以下
$in	配列に含まれる
$nin	配列に含まれない
$and	論理 AND
$or	論理 OR

アーキテクチャ

ConvexVector は、次の構造でベクトルを mastra_vectors テーブルに保存します。

• id: 一意のベクトル識別子
• indexName: インデックス名
• embedding: ベクトルデータ（浮動小数点数の配列）
• metadata: 省略可能な JSON メタデータ

ベクトル類似度検索は、Mastra アダプターでコサイン類似度を使用して実行されます。柔軟にセットアップできますが、大規模な本番ベクトルコレクション向けには設計されていません。

ConvexNativeVector は、Mastra の各ベクトルインデックスを専用の Convex テーブルに保存します。クエリでは ctx.vectorSearch を使用する Convex action を呼び出し、一致したドキュメントを Convex query で読み込みます。これは Convex ネイティブのベクトル検索モデルに準拠しています。

• ベクトルインデックスは convex/schema.ts で宣言します。
• ベクトル検索は Convex action から実行します。
• topK は 1 から 256 の範囲で指定する必要があります。
• フィルターは Convex ベクトルインデックスの filterFields に列挙したフィールドを対象にする必要があります。
• インデックスをまたぐ結果を避けるため、Mastra のベクトルインデックスごとに専用テーブルを使用します。

実行時に定義するインデックス作成、メタデータのみのクエリ、複雑なフィルター演算子、フィルターベースの一括更新や削除、または Convex ネイティブベクトル検索の上限を超える結果数が必要な場合は、外部のベクトルデータベースを使用してください。

関連情報

• Convex ストレージ
• メタデータフィルター
• Convex ドキュメント