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

## 1. 概要

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

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

```mermaid
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`）。

- ベクトルが使えない場合（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** を参照。
