データベース仕様 (Database Specification)

1. 概要

SQLite をメタデータ・ベクトル・全文検索のいずれにも利用します。vec_items の次元数はエディションにより異なります（Community: 50、Pro: 768）。検索は FTS5 とベクトル検索のハイブリッドです。

2. エンティティとテーブル

erDiagram
    documents ||--o{ items : "1:N"
    items ||--|| vec_items : "1:1"
    items ||--|| items_fts : "1:1 (FTS5)"
    items ||--o| items_lsa : "1:1 (Community)"

    documents {
        int id PK
        text path UK
        text mime
        datetime created_at
        datetime updated_at
    }
    items {
        int id PK
        int document_id FK
        int chunk_index
        text content
        datetime created_at
        datetime updated_at
    }
    vec_items {
        int id PK "items.id"
        blob embedding "50d(Community) or 768d(Pro)"
    }
    items_fts {
        int rowid PK
        text content "FTS5 trigram"
    }
    items_lsa {
        int id PK "Community: LSA 用メタデータ"
        blob 等
    }

• documents: 文書単位のメタデータ（path, mime）。
• items: チャンク。同一 document_id で結合すると文書全文。
• vec_items: vec0 拡張の仮想テーブル。Community は 50 次元、Pro は 768 次元。
• items_fts: FTS5（trigram）。両エディションで共通。
• items_lsa: Community 版の LSA 用中間データ。Pro では未使用。

3. ハイブリッド検索

1. ベクトル検索: クエリを LSA（Community）または埋め込みモデル（Pro）でベクトル化し、vec_items 上で類似度検索（HNSW または vec0 MATCH）。類似度は 0〜1 に正規化。
2. 全文検索: FTS5 の bm25 等でスコア算出し、同様に 0〜1 に変換。

3. マージ: 各チャンク ID について、両スコアの大きい方を採用し、降順でランキング。必要に応じて文書単位にまとめ（group_by_document）。

4. ベクトルが使えない場合（Pro でモデル未ロード等）は FTS のみで検索可能。

4. ベクトル次元不一致時の vec_items 再作成

• 起動時に initialize_database で現在の vec_items のテーブル定義（sqlite_master）を確認する。
• 期待する次元（Community: 50、Pro: 768）と FLOAT[n] が一致しなければ、vec_items を DROP してから正しい次元で再 CREATE する。
• 再作成後は vec_items が空になるため、RE-INDEX（lsa_retrain）またはヒーリングで再ベクトル化する。実装: db::check_and_init_vector_table。

5. 同期・ヒーリング

• 起動時: items に対応する items_fts / vec_items（および Community の items_lsa）の不足を補完。
• 手動: GET /heal で FTS の不足行を同期。Pro の vec_items 不足は RE-INDEX（lsa_retrain）で補完。

6. 内部管理

• internal_metadata: スキーマバージョン等。マイグレーションで参照。

Pro のベクトル化・ANN の詳細は 07_embedding_tract.md・11_pro_vectorization_and_ann.md を参照。