# データベース・ハイブリッド検索仕様書 (Database & Hybrid Search Specification)

## 1. データベース設計思想

本システムでは、SQLite を単なるメタデータストレージとしてだけでなく、**「ベクトル検索エンジン」**および**「全文検索エンジン（FTS5）」**としても活用しています。これにより、意味的な類推（Vector）と厳密なキーワード一致（BM25）を両立させた、堅牢なハイブリッド検索エンジンを実現しています。

### 1.1 ハイブリッド検索の採用理由

データが少ない初期段階では LSA（Latent Semantic Analysis）による学習が不十分で、語彙の関連性を正しく導き出せない「コールドスタート」問題が発生します。これに対処するため、統計的な重み付けを行う **BM25 スコアリング** 可能な全文検索（FTS5）を併用しています。

- **Vector (LSA)**: 「意味」が似ているものを探す。データ量が増えるほど賢くなる。
- **FTS5 (BM25)**: 「文字」が合っているものを探す。1件目のデータから正確に動作する。
- **指標**: `Max(Vector Similarity, BM25 Score)` に基づくランキング。

## 2. エンティティ関係定義 (ERD)

```mermaid
erDiagram
    documents ||--o{ items : "Contains (1:N)"
    items ||--|| vec_items : "Vector Index (1:1)"
    items ||--|| items_lsa : "LSA Metadata (1:1)"
    items ||--|| items_fts : "Full-text Index (1:1)"

    documents {
        integer id PK "文書ID"
        text path "出典・パス (Unique)"
        text mime "MIMEタイプ"
        datetime created_at "作成日"
        datetime updated_at "更新日"
    }
    items {
        integer id PK "チャンクID"
        integer document_id FK "documents.id 参照"
        integer chunk_index "チャンク順番"
        text content "テキスト本体"
        datetime created_at "作成日"
        datetime updated_at "更新日"
    }
    vec_items {
        integer id PK "items.id と紐付け"
        blob embedding "50次元ベクトルデータ(f32)"
    }
    items_fts {
        integer rowid PK "items.id と紐付け"
        text content "全文検索用インデックス"
    }
```

## 3. ハイブリッド検索アルゴリズム

### 3.1 `search_text` のロジック

検索クエリが入力されると、システムは以下の **2系統の検索** を並列または逐次実行して結果をマージします。

1. **セマンティック検索 (Vector)**:
   - クエリを LSA Engine で 50 次元のベクトルに射影。
   - `vec_items` から L2 距離が近い順に取得し、`1.0 - (distance / 2.0)` で類似度を算出。
2. **統計キーワード検索 (FTS5/BM25)**:
   - クエリを `trigram` トークナイザー（3文字単位）で分解。
   - SQLite FTS5 の `bm25()` 関数を用いて、文書内の重要度を算出。
   - BM25 スコアを `(1.0 - tanh(score/10))` 等で 0-1 の類似度に変換。

**最終スコア**: 各 ID ごとに 2 つのスコアのうち高い方（Max）を採用し、降順でランキングします。

## 4. テーブル詳細

### 4.1 `items` (チャンク管理)

文書を分割したテキストを保持。すべての検索インデックスのソースとなります。

### 4.2 `vec_items` (ベクトル演算用仮想テーブル)

`sqlite-vec` による仮想テーブル。LSA エンジンが生成した特徴量を保持します。

### 4.3 `items_fts` (全文検索用仮想テーブル)

SQLite `FTS5` 拡張による仮想テーブル。`tokenize='trigram'` を指定することで、日本語のわかち書きに依存しない強力な部分一致・統計検索をサポートします。

### 4.4 `items_lsa` (LSAメタデータ)

LSA の学習・推論に使用する中間データ（特徴量 blob）を保持します。

### 4.5 `internal_metadata` (内部管理テーブル)

システムバージョン（`0.3.0`）等を保持し、スキーマの互換性を管理します。
