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

1. 物理構造

データベースは単一の SQLite ファイル (telos.db) として管理されます。メタデータ管理用の標準テーブルと、sqlite-vec によるベクトル演算用の仮想テーブルの 2 つで構成されます。

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

erDiagram
    items ||--|| vec_items : "1:1 Mapping (id)"
    
    items {
        integer id PK "Primary Key (Autoincrement)"
        text content "文書本文"
        text path "ファイルパス / 出典識別子"
        datetime created_at "作成日時"
        datetime updated_at "更新日時 (Auto-trigger)"
    }
    
    vec_items {
        integer id PK "items.id と同一"
        blob embedding "640-dim Vector (f32)"
    }

3. 詳細テーブル定義

3.1 items テーブル

3.2 vec_items (Virtual Table)

sqlite-vec (vec0) モジュールを使用した仮想テーブルです。

• ID: items.id と同期。
• ベクトル構成:
  • 次元数: 640次元 (Gemma-3 270m モデルの仕様)。
  • データ型: FLOAT[640] (内部的には BLOB)
  • L2距離: MATCH 演算子による高速な近傍探索。

4. 検索仕様

4.1 セマンティック探索クエリ

SELECT
  i.id,
  i.content,
  v.distance
FROM items i
JOIN vec_items v ON i.id = v.id
WHERE v.embedding MATCH :query_vector -- ベクトル近傍マッチング
  AND k = :k -- 返却件数 (LIMIT とは別に必要)
ORDER BY distance;

4.2 フォールバック検索

LLM サーバーが停止している場合、sqlite-vec による検索が不可能なため、content LIKE %?% による全文検索へ自動的にフォールバックします。

5. 動的維持管理 (Self-Healing)

1. 次元検知: 起動時に内蔵 LLM サーバーからダミー埋め込みを取得し、期待される次元（640）を確認。
2. テーブル整合性: vec_items 側のデータが不足している、または次元が異なる場合、バックグラウンドで items からベクトルを再生成し修復します（db::sync_vectors）。
3. トランザクション: items と vec_items への登録はアトミックに行われ、片方のみの登録が残らないよう制御されています。