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

# Upstash vector store

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

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

**url** (`string`): Upstash Vector データベースの URL

**token** (`string`): Upstash Vector API トークン

## メソッド

### `createIndex()`

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

**indexName** (`string`): 作成するインデックスの名前

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

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 類似度検索の距離指標 (Default: `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`): 返す結果の数 (Default: `10`)

**filter** (`Record<string, any>`): クエリのメタデータフィルター

**includeVector** (`boolean`): 結果にベクトルを含めるかどうか (Default: `false`)

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

**queryMode** (`QueryMode`): 検索モード: 密検索のみの場合は 'DENSE'、疎検索のみの場合は 'SPARSE'、複合検索の場合は 'HYBRID'

### `listIndexes()`

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

### `describeIndex()`

**indexName** (`string`): 詳細を取得するインデックスの名前

戻り値:

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

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

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

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

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

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

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

## レスポンス型

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

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

## エラー処理

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

```typescript
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**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

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

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

## 関連情報

- [メタデータフィルター](https://mastra.zisheng.pro/ja/reference/rag/metadata-filters)