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

1. 物理構造

データベースは単一の SQLite ファイルとして管理されます。メタデータ管理用の標準テーブルと、ベクトル演算用の仮想テーブルの 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 "作成日時 (Default: localtime)"
        datetime updated_at "更新日時 (Auto-trigger)"
    }
    
    vec_items {
        integer id PK "items.id と同一"
        blob embedding "768-dim Vector (f32 LE)"
    }

3. 詳細テーブル定義

3.1 `items` テーブル

カラム	型	NULL	初期値	説明
`id`	INTEGER	NO	AUTOINC	保存文書のユニーク ID
`content`	TEXT	NO	-	元のテキストデータ
`path`	TEXT	YES	-	ドキュメントの出典メタデータ
`created_at`	DATETIME	NO	CURRENT	登録時のタイムスタンプ
`updated_at`	DATETIME	NO	CURRENT	更新時のタイムスタンプ

3.2 `vec_items` (Virtual Table)

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

ID: items.id と同期。
ベクトル構成:
- 次元数: 768次元 (Gemma 3 300M モデルに準拠)
- データ型: FLOAT[768] (内部的には BLOB 表現)
- 保存形式: IEEE 754 32bit Float (Little Endian) バイト列

4. 検索仕様

4.1 演算アルゴリズム

sqlite-vec は、近似最近傍探索 (ANN) において以下の距離関数をサポートし、本システムでは MATCH 演算子による高速検索を実施します。

デフォルト距離計算: L2 (Euclidean) 距離。
インデックス: シャドウテーブルを介したベクトル専用インデックス。

4.2 標準検索クエリ

SELECT
  i.id,
  i.content,
  v.distance
FROM vec_items v
JOIN items i ON v.id = i.id
WHERE embedding MATCH :query_vector
ORDER BY distance
LIMIT :limit;

5. 整合性制御

トランザクション: アイテム登録時、items への登録が成功した後にのみ、関連付けられた ID で vec_items への書き込みが行われます。
トリガー: items テーブルに updated_at 自動更新用の SQLite トリガーを実装。