# データベース・ベクトル検索仕様書 (Database & Search Specification)

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

本システムでは、SQLite を単なるメタデータストレージとしてだけでなく、**「ベクトル検索エンジン」**としても活用しています。これにより、ACID 特性（データの整合性保証）を維持しながら、高速なセマンティック検索を実現しています。

### 1.1 sqlite-vec の役割

`sqlite-vec` エクステンションを採用することで、標準的な SQL クエリの中でベクトル間の「距離計算」が可能になります。

- **メリット**: 文書（Text）と特徴量（Vector）を別々のデータベースに分けずに済み、トランザクションの一貫性が保たれます。
- **距離指標**: 本システムでは「L2 距離（二乗和の平方根）」を使用し、値が小さいほど類似度が高いと判断します。

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

```mermaid
erDiagram
    documents ||--o{ items : "Contains (1:N)"
    items ||--|| vec_items : "Reference by ID (1:1)"
    items ||--|| items_lsa : "Metadata by ID (1:1)"

    documents {
        integer id PK "文書ID (自動採番)"
        text path "出典・ファイルパス (Unique)"
        text mime "MIMEタイプ (text/markdown等)"
        datetime created_at "作成日"
        datetime updated_at "更新日"
    }
    internal_metadata {
        text key PK "管理キー (version等)"
        text value "設定値"
    }
    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_lsa {
        integer item_id PK "items.id と紐付け"
        text feature_json "特徴量メタデータ"
    }
```

## 3. ベクトル検索とセルフヒーリング

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

検索クエリが入力されると、システムは以下の手順を踏みます。

1. クエリを内部の **LSA Engine** に送り、現在のボキャブラリに基づいて 50 次元のベクトルに射影する。
2. SQLite 上で `vec_items` テーブルをスキャンし、クエリベクトルに近い順（L2距離順）に `items.id` を取得。
3. `items` テーブルから実際のテキストを取得して結合。

### 3.2 セルフヒーリング (Self-healing) の必要性

モデルの変更や、インポート時の中断などにより、`items` にテキストはあるが `vec_items` に対応するベクトルが存在しない「不整合状態」が稀に発生し得ます。
本システムは `db::sync_vectors` ロジックを備えており：

- 起動時または特定のトリガーで `items` を全走査。
- ベクトルが欠落している行を自動検出し、LSA エンジンで再生成・補完。
これにより、常に検索結果の網羅性を保証します。

## 4. テーブル詳細

### 4.1 `documents` (文書メタデータ管理)

各ソース（ファイル等）の一意な情報を保持します。`path` カラムにより同一ソースの重複登録を防ぎ、`mime` カラムでファイル形式を識別します。

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

文書を一定の長さ（例：800文字）で分割した「チャンク」を保持します。`document_id` で親文書と紐付けられ、`chunk_index` で順序が管理されます。

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

`sqlite-vec` によって定義された仮想テーブルです。`dimensions=50` として設定されており、LSA エンジンの射影次元数と一致させています。

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

LSA の計算に使用された中間データや、特定の単語重みなどのメタ情報を保持します。将来的なインデックス再構築の高速化に使用されます。

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

システム内部で利用する設定値や状態を保持します。

| カラム名 | 型 | 説明 |
| :--- | :--- | :--- |
| `key` | TEXT | **主キー**。管理用のキー（例: `version`） |
| `value` | TEXT | キーに対応する値（例: `0.3.0`） |
