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

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

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

1.1 sqlite-vec の役割

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

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

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

erDiagram
    items ||--|| vec_items : "Reference by ID (1:1)"

    items {
        integer id PK "文書ID (自動採番)"
        text content "原文テキスト"
        text path "出典・メタデータ"
        datetime created_at "作成日"
    }

    vec_items {
        integer id PK "items.id と紐付け"
        blob embedding "640次元ベクトルデータ(f32)"
    }

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

3.1 `search_text` のロジック

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

クエリを llama-server に送り、ベクトル化する。
SQLite 上で vec_items テーブルをスキャンし、クエリベクトルに近い順（L2距離順）に items.id を取得。
items テーブルから実際のテキストを取得して結合。

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

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

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

4. テーブル詳細

4.1 `items` (メタデータ管理)

文書の本体と、それに付随する情報を保持します。path カラムは、将来的なローカルパス連携や URL 参照を想定した自由形式の文字列です。

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

sqlite-vec によって定義された仮想テーブルです。dimensions=640 として設定されており、Gemma-3 の出力層と完全一致させています。