20. schema が宣言したものを索引に持たせる

Status: accepted
Date: 2026-09-09
Deciders: プロジェクトオーナー
Applies to: v1.9.0

背景と課題

ADR-0019 は、 frontmatter の key をパーサにすべて保持させ、groove-schema.toml がそのどれでも名指せるようにして、そこで止まった。保持された key が届く先は groove validate だけで、それ以外は何も無かった。それを求めたのと同じユーザ (#289) が、残りの代償がどこにあるかを示した。 4 つのメタデータ軸を持つ 74 文書のコーパスにおいて、1,036 件のタグの出現のうち 434 件は、 status / environment / team / source を tags へ写すためだけに存在している。検索フィルタから見える frontmatter が tags しか無いからである。その写しを正しく保つには外部バリデータが要り、topic は文書の種別に費やされてしまう。ユーザが求めたのは 1 つだけである: 保持された key でのフィルタ、完全一致の文字列比較、演算子は無し、schema が宣言した key に限る。

本決定が答える問い: 宣言された key を索引へ持ち込むのは誰で、それはいつか — schema を読む indexer か、それとも schema を読むクエリか。

判断の軸

「schema が宣言した key に限る」は、呼び出し側がフィルタできるものについて真でなければならない。 今日の schema ファイルが何を書いているか、だけの話ではない。どんな key でも受け取って、たまたま当たったら答えるフィルタ面は、この機能ではない
schema は運用者が実行と実行の間に編集するファイルである。 search も serve もこれを読んでおらず、読む必要も無いはずである: クエリは索引から答える
変更されていない文書は読み直されない。 indexer はハッシュが一致するファイルを読み飛ばすので、新しい key を宣言した schema は、変更されなかった文書には永久に届かない — #251 が frontmatter_policy で踏んだのと同じ罠である
frontmatter_unparsed は CI が判定に使う数である。 新しい理由で健全な文書を読み直すパスが、それらを壊れているものとして数えてはならない
結果の面とフィルタの面は凍結されている (docs/stability.md): フィールドの追加は minor リリース、意味の変更はそうではない。データベース内部のスキーマは契約ではない
報告者のベンチマークは deprecated-trap というクラスを記録しており、それを閉じられるのは除外だけである。そして報告者は演算子を求めていない

検討した選択肢

indexer が schema を読み、宣言された key の値を専用のテーブルへ格納する。search はそのテーブルでフィルタし、schema を一切読まない。 採用
パーサが保持したスカラをすべて格納し、key の妥当性はクエリ時に schema に照らして検証する。 却下: serve と groove search の両方が schema を読み込む必要が生じ、 schema を持たない知識ベースには別の規則が要り、索引は誰も宣言していない値を抱えることになる
documents 上の JSON カラムに持ち、tags と同じくクエリの後に Rust 側でフィルタする。 却下: テーブルを分ければクエリ自身が絞り込め、リストの値は 2 つ目のエンコーディングではなく 2 行目になる
除外を演算子にする (status!=deprecated)。 却下: 報告者が求めたのは完全一致であり、演算子は求めていない。2 つ目のフラグ --field-not / fields_not は、除外に完全一致と同じ形を与え、値の文法には手を触れない

決定

groove index は毎回 <kb_path>/groove-schema.toml を読む — groove validate が読むのと同じファイルである。そこで宣言された key から、パーサが自分のフィールドに格納する 5 つを除いたものが宣言された集合である。読み込めない schema は、そのエラーとともに索引を止める。読み込めない設定がバイナリを止めるのと同じである: それ無しで索引してしまえば、すべてのフィールドフィルタが空を答え、しかも何も言わないことになる
宣言された key の値は文書ごとに document_fields へ格納する。 スカラは 1 行、リストは要素ごとに 1 行で、パーサが保持していた文字列そのままである。不透明な形と null は値を持たないので何も書かない。宣言されていない key は索引の関知するところではない。この行を持つのは Markdown だけである
宣言された集合は世代キーである。 index_meta.declared_fields が、完了した実行の使った集合を記録する。schema が宣言する集合がそれと異なるとき、その実行は変更されていない Markdown 文書をもう一度だけ読み、再埋め込みはせずに行を書き直す。このとき健全な文書を frontmatter が壊れたものとして数えることはないので、[index].fail_on_frontmatter_error は schema の変更の影響を受けない。このキーより前に作られた索引は、集合が変わったものとして扱われる
search はそのテーブルでフィルタする。 fields は、与えられたすべての key についてその値のいずれかを持つ文書を残す。fields_not は、与えられた key のいずれかについてその値のいずれかを持つ文書を落とし、その key を持たない文書は残す。比較は完全一致のバイト単位である。索引に無い key は何にも一致せず、エラーにもならない。判定の門は索引だからである。コマンドラインでの綴りは --field key=value / --field-not key=value で、繰り返し指定でき、最初の = で分割する。ツールは fields / fields_not を key → 文字列のリスト として受け取る — 綴りを 1 つにしたのは、ツールスキーマにおける string | list の union こそ schema_compat が避けるために存在する形だからである (#75) — そして filter_applied がそれを返す
graph は変更しない。 フィルタを get_connection_graph へ広げるのは後の決定である

結果と代償

groove-schema.toml は今やバリデーションだけでなく索引の入力でもある。 schema を編集すれば、次の groove index がそれに追随する。フラグは要らない
filter_applied に現れ得る行が 2 つ、ツールのパラメータが 2 つ、フラグが 2 つ増えた: docs/stability.md の下で minor リリースである
document_fields は 1.8.0 が作った索引には無いテーブルである。 1.9.0 で開けばテーブルが作られ、最初の groove index がそれを埋める
検索のベクトル脚は、この述語を sqlite-vec の KNN クエリに付け足す。 それが受理され、かつ正しいことをテストが固定している。将来の sqlite-vec がこれを拒否するようになったら、この脚は他のフィルタが既にそうしているのと同じく、クエリの後に Rust 側でフィルタする形へ退避する
doctor はまだこのテーブルを見ない。status もこれを数えない (2026-09-10、v1.11.0) 解消: doctor は declared-fields-pending (集合が未記録 = field filter 付きの検索が拒否されるすべての状態) と declared-fields-stale (記録済みの集合が disk 上の schema と食い違う) を報告し、 status は記録済みの集合と行数を出す。どちらも検索が見るのと同じ index_meta の key を読み、indexer と同じ declared_field_names を呼ぶ — 規則を作り直してはいない
groove index が読むのは <kb_path>/groove-schema.toml だけである。 別の場所に置いて groove validate --schema <path> に渡している schema は索引から見えないので、それに対する --field / --field-not フィルタは空を返す

参考

Issue #289 (設計の入力、コーパスと要望)
パーサが何を保持するかは ADR-0019。この記録が決めるのは索引が何を保持するかである
grooveseek/src/indexer.rs (declared_field_names / declared_field_rows)、 grooveseek/src/db/search.rs (field_predicates)、docs/filters.md