Upstash vector store

UpstashVector クラスは、メタデータフィルターを使用したベクトル類似度検索とハイブリッド検索に対応するサーバーレスベクトルデータベースサービス Upstash Vector を使用したベクトル検索を提供します。

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

url:

string

Upstash Vector データベースの URL

token:

string

Upstash Vector API トークン

メソッド

createIndex()

注: Upstash ではインデックスが自動的に作成されるため、このメソッドは何も行いません。

indexName:

string

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

dimension:

number

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

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

類似度検索の距離指標

upsert()

indexName:

string

upsert 先のインデックス名

vectors:

number[][]

埋め込みベクトルの配列

sparseVectors?:

{ indices: number[], values: number[] }[]

ハイブリッド検索用の疎ベクトルの配列。各疎ベクトルの indices 配列と values 配列の要素数は一致させる必要があります。

metadata?:

Record<string, any>[]

各ベクトルのメタデータ

ids?:

string[]

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

query()

indexName:

string

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

queryVector:

number[]

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

sparseVector?:

{ indices: number[], values: number[] }

ハイブリッド検索用の省略可能な疎ベクトル。indices 配列と values 配列の要素数は一致させる必要があります。

topK?:

number

= 10

返す結果の数

filter?:

Record<string, any>

クエリのメタデータフィルター

includeVector?:

boolean

= false

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

fusionAlgorithm?:

FusionAlgorithm

ハイブリッド検索で密検索と疎検索の結果を統合するアルゴリズム（RRF - Reciprocal Rank Fusion など）

queryMode?:

QueryMode

検索モード: 密検索のみの場合は 'DENSE'、疎検索のみの場合は 'SPARSE'、複合検索の場合は 'HYBRID'

listIndexes()

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

describeIndex()

indexName:

string

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

戻り値:

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

deleteIndex()

indexName:

string

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

updateVector()

indexName:

string

更新するインデックスの名前

id:

string

更新する項目の ID

update:

object

ベクトル、疎ベクトル、メタデータのいずれかを含む更新オブジェクト

update オブジェクトには次のプロパティを指定できます。

• vector（省略可能）: 新しい密ベクトルを表す数値の配列。
• sparseVector（省略可能）: ハイブリッドインデックス用の indices 配列と values 配列を持つ疎ベクトルオブジェクト。
• metadata（省略可能）: メタデータのキーと値のペアを持つレコード。

deleteVector()

indexName:

string

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

id:

string

削除する項目の ID

指定したインデックスから ID に基づいて項目の削除を試みます。削除に失敗した場合はエラーメッセージをログに記録します。

ハイブリッドベクトル検索

Upstash Vector は、セマンティック検索（密ベクトル）とキーワードベースの検索（疎ベクトル）を組み合わせ、関連性と精度を向上させるハイブリッド検索をサポートしています。

基本的なハイブリッド検索の使用方法

import { UpstashVector } from '@mastra/upstash'

const vectorStore = new UpstashVector({
  id: 'upstash-vector',
  url: process.env.UPSTASH_VECTOR_URL,
  token: process.env.UPSTASH_VECTOR_TOKEN,
})

// Upsert vectors with both dense and sparse components
const denseVectors = [
  [0.1, 0.2, 0.3],
  [0.4, 0.5, 0.6],
]
const sparseVectors = [
  { indices: [1, 5, 10], values: [0.8, 0.6, 0.4] },
  { indices: [2, 6, 11], values: [0.7, 0.5, 0.3] },
]

await vectorStore.upsert({
  indexName: 'hybrid-index',
  vectors: denseVectors,
  sparseVectors: sparseVectors,
  metadata: [{ title: 'Document 1' }, { title: 'Document 2' }],
})

// Query with hybrid search
const results = await vectorStore.query({
  indexName: 'hybrid-index',
  queryVector: [0.1, 0.2, 0.3],
  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
  topK: 10,
})

高度なハイブリッド検索オプション

import { FusionAlgorithm, QueryMode } from '@upstash/vector'

// Query with specific fusion algorithm
const fusionResults = await vectorStore.query({
  indexName: 'hybrid-index',
  queryVector: [0.1, 0.2, 0.3],
  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
  fusionAlgorithm: FusionAlgorithm.RRF,
  topK: 10,
})

// Dense-only search
const denseResults = await vectorStore.query({
  indexName: 'hybrid-index',
  queryVector: [0.1, 0.2, 0.3],
  queryMode: QueryMode.DENSE,
  topK: 10,
})

// Sparse-only search
const sparseResults = await vectorStore.query({
  indexName: 'hybrid-index',
  queryVector: [0.1, 0.2, 0.3], // Still required for index structure
  sparseVector: { indices: [1, 5], values: [0.9, 0.7] },
  queryMode: QueryMode.SPARSE,
  topK: 10,
})

ハイブリッドベクトルの更新

// Update both dense and sparse components
await vectorStore.updateVector({
  indexName: 'hybrid-index',
  id: 'vector-id',
  update: {
    vector: [0.2, 0.3, 0.4],
    sparseVector: { indices: [2, 7, 12], values: [0.9, 0.8, 0.6] },
    metadata: { title: 'Updated Document' },
  },
})

レスポンス型

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

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

エラー処理

store は捕捉可能な型付きエラーをスローします。

try {
  await store.query({
    indexName: 'index_name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details) // Additional error context
  }
}

環境変数

必要な環境変数:

• UPSTASH_VECTOR_URL: Upstash Vector データベースの URL
• UPSTASH_VECTOR_TOKEN: Upstash Vector API トークン

使用例

fastembed を使用したローカル埋め込み

埋め込みは、memory の semanticRecall がキーワードではなく意味に基づいて関連メッセージを取得するために使用する数値ベクトルです。この設定では、@mastra/fastembed を使用してベクトル埋め込みを生成します。

使用を開始するには fastembed をインストールします。

npm

npm install @mastra/fastembed@latest

pnpm

pnpm add @mastra/fastembed@latest

Yarn

yarn add @mastra/fastembed@latest

Bun

bun add @mastra/fastembed@latest

Agent に次の設定を追加します。

src/mastra/agents/example-upstash-agent.ts

import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { UpstashStore, UpstashVector } from '@mastra/upstash'
import { fastembed } from '@mastra/fastembed'

export const upstashAgent = new Agent({
  id: 'upstash-agent',
  name: 'Upstash Agent',
  instructions:
    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new UpstashStore({
      id: 'upstash-agent-storage',
      url: process.env.UPSTASH_REDIS_REST_URL!,
      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
    }),
    vector: new UpstashVector({
      id: 'upstash-agent-vector',
      url: process.env.UPSTASH_VECTOR_REST_URL!,
      token: process.env.UPSTASH_VECTOR_REST_TOKEN!,
    }),
    embedder: fastembed,
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
      },
    },
  }),
})

関連情報

• メタデータフィルター