# FTS5 フルテキスト検索

Synapse は高速かつ柔軟なメモリ検索のために FTS5（Full-Text Search 5）を使用しています。本ページでは、その仕組みと効果的な使い方を説明します。

## FTS5 とは？

FTS5 はフルテキスト検索機能を提供する SQLite 拡張（PostgreSQL でも拡張経由で利用可能）です。以下をサポートします。

- テキストコンテンツのインデックスによる高速キーワード検索
- ブール演算子（AND、OR、NOT）
- 引用符によるフレーズマッチング
- `*` によるプレフィックスマッチング
- 関連度による結果ランキング

Synapse は全メモリコンテンツを FTS5 でインデックス化し、数千件のメモリにわたるサブミリ秒検索を可能にしています。

## Synapse での FTS5 利用

`POST /memory` 時の処理：

1. メモリコンテンツが `memories` テーブルに保存
2. コンテンツが FTS5 仮想テーブルにも挿入
3. FTS5 が自動的にトークン化とインデックス化を実行

`GET /memory/search?q=...` 時の処理：

1. Synapse が FTS5 構文でクエリを解析
2. FTS5 インデックスに対して `MATCH` を実行
3. `mind_id` でフィルタ（テナント分離）
4. ランク付けされた結果を返却

## クエリ構文

### 単純なキーワード検索

```
?q=docker
```

「docker」を含むメモリを返します。

### 複数キーワード（暗黙の AND）

```
?q=docker+swarm
?q=docker%20swarm
```

「docker」と「swarm」の両方を含むメモリを返します。

### フレーズマッチング

```
?q="docker+swarm"
?q=%22docker%20swarm%22
```

完全なフレーズ「docker swarm」を含むメモリを返します。

### プレフィックスマッチング

```
?q=docker*
```

「docker」で始まる単語（「dockers」「dockerfile」「dockerize」など）を含むメモリを返します。

### ブール OR

```
?q=docker+OR+kubernetes
```

「docker」または「kubernetes」を含むメモリを返します。

### ブール NOT

```
?q=docker+-swarm
?q=docker+NOT+swarm
```

「docker」を含むが「swarm」を含まないメモリを返します。

### グループ化

```
?q=(docker+OR+kubernetes)+-test
```

「docker」または「kubernetes」を含むが「test」を含まないメモリを返します。

## 実践例

### プロジェクトに関するメモリの検索

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=synapse+deployment"
```

### 完全フレーズの検索

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22"
```

### テストメモリの除外

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=production+-test"
```

### 技術による検索

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql"
```

## ランキング

FTS5 は BM25 アルゴリズムで関連度により結果をランク付けします。考慮要素：

- 用語頻度（用語の出現回数）
- 逆文書頻度（まれな用語ほど上位）
- 文書長（短い文書ほど上位）
- カラムウェイト（title > content）

結果はランク順（最も関連度の高いものが先頭）で返されます。

## パフォーマンス

| 操作 | レイテンシ |
|-----------|---------|
| 100 件のメモリ検索 | < 5ms |
| 1,000 件のメモリ検索 | < 10ms |
| 10,000 件のメモリ検索 | < 25ms |
| 100,000 件のメモリ検索 | < 100ms |

FTS5 は読み取り中心のワークロードに高度に最適化されています。

## 制限事項

### ステミング

FTS5 はデフォルトでステミングを行いません。「running」と「run」は異なる用語として扱われます。

**回避策：** プレフィックスマッチングを使用 — `?q=run*`

### 誤字許容

FTS5 はファジーマッチングをサポートしません。誤字があると結果が返りません。

**回避策：** 概念マッチングにはセマンティック検索（`/memory/semantic-search`）を使用してください。

### ストップワード

一般的な単語（the、a、an、is）はインデックス化されますが、検索には有用でない場合があります。FTS5 はこれを自動的に処理します。

## FTS5 とセマンティック検索の比較

| 側面 | FTS5 | セマンティック検索 |
|--------|------|-----------------|
| 速度 | サブミリ秒 | 50〜100ms |
| マッチング | 完全キーワード | 概念的 |
| 誤字許容 | なし | 一部あり |
| ステミング | なし | 暗黙的 |
| 埋め込み必要 | 不要 | 必要 |
| 最適な用途 | 特定の用語 | 概念 |

キーワードが分かっている場合は FTS5 を使用してください。X が異なる表現で記述されている「X に関するメモリ」を探す場合はセマンティック検索を使用してください。

## ベストプラクティス

> [!TIP]
> - **具体的な用語を使用** — 「container orchestration」より「docker swarm」が良い
> - **フレーズを引用** — `"docker swarm"` でフレーズマッチを確実に
> - **バリエーションにプレフィックス** — `deploy*` で「deploy」「deployment」「deploying」を捕捉
> - **ノイズを除外** — `-test` でテストメモリをフィルタ
> - **タグと組み合わせ** — `?q=docker&tag=production` で結果を絞り込み

## 次のステップ

- [Semantic Search](/docs/concepts/semantic-search)
- [Memory API](/docs/api/memory)
- [Memory Best Practices](/docs/guides/memory-best-practices)