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

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

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

1.1 sqlite-vec の役割

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

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

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

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)"
        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_lsa {
        integer item_id PK "items.id と紐付け"
        text feature_json "特徴量メタデータ"
    }

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

3.1 `search_text` のロジック

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

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

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

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

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

4. テーブル詳細

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

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

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

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

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

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

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

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