Markdown 索引ジョブ

索引は原本に追従する側であって、原本ではない

原本は Markdown ファイルのまま。索引はそこから機械的に作る一方向の生成物で、失っても rm して作り直せる。ただし作り直さないと実体からズレるので、定期的に追従させる必要がある。このジョブの仕事はそれだけである。

7つの段階と、途中で降りる3つの出口

スケジューラが起動するのは薄いラッパースクリプトで、その中から索引本体を呼ぶ。ラッパーが存在する理由は、索引本体が「成功したが何もしなかった」と「死んだ」を区別できないから。

実際のログ出力

15:24:49  PATHS corpus=~/notes-repo db=~/.local/share/notes-index/index.sqlite build=…
15:24:50  INFO  run done rc=0 elapsed=1s chunks=10237 files=367 stale=no
                idx=2026-09-04T15:05:22 fs=2026-09-04T15:05:22 newest=notes/2026-09-04.md

• chunks / files — 索引に載っている総数。増減がそのまま見える
• stale — 索引本体の自己申告ではなく、別経路で測り直した鮮度。yes なら索引が実ファイルに追いついていない
• idx / fs — 索引側の最終更新時刻と、実ファイル側の最新更新時刻。この2つの比較が stale の中身
• newest — いま一番新しいファイル。stale=yes のとき犯人を特定するために出している

索引に入れないものを、4段階で落とす

対象ディレクトリを再帰的に歩き、拡張子・ディレクトリ名・サブモジュール・バージョン管理の除外設定の4段階でふるいにかける。安い判定から順に並べてある。

索引の中身の偏り

実データではチャンクの77.6%が上位2ディレクトリに集中していた。この偏りは検索精度を直接壊すので、既定の検索範囲からその2つを外し、必要なときだけ明示的に戻す設計にしている。

見出しで割り、短すぎれば併合し、長すぎれば重ねて分ける

1ファイル＝1レコードにはしない。検索が返すのは「どのファイルか」ではなく「そのファイルのどこか」でなければ意味がないため、見出し構造を使って本文を切り分ける。

2つの関門で、書き戻す量を絞る

毎回すべてを作り直すと1.68秒かかる。実運用ではほとんどのファイルが変わっていないので、2段階の関門で「触らなくていいもの」を落としていく。結果として通常の実行は0〜1秒で終わる。

テーブルは2つだけ

本文テーブルが1つと、設定を持つキー・バリューが1つ。全文検索用の仮想テーブルもベクトル用のテーブルも無い。検索は素の部分一致で行う。

CREATE TABLE chunks (
  chunk_id        TEXT    PRIMARY KEY,   -- 決定的なハッシュ（パス＋序数＋分割規則の版）
  path            TEXT    NOT NULL,      -- 対象ルートからの相対パス
  heading_path    TEXT    NOT NULL DEFAULT '',
  start_line      INTEGER NOT NULL,
  end_line        INTEGER NOT NULL,
  text            TEXT    NOT NULL,
  chunk_sha       TEXT    NOT NULL,
  domain          TEXT    NOT NULL,      -- パス第1階層
  doc_date        TEXT,                  -- 'YYYY-MM-DD' または NULL
  doc_date_source TEXT,
  mtime           INTEGER NOT NULL,      -- 更新時刻（整数ナノ秒）

  -- 将来の意味検索用に、列だけ空けてある（現在は全件 NULL）
  embedding       BLOB,
  embedding_space TEXT,
  stored_dim      INTEGER,
  stored_dtype    TEXT,

  CHECK (start_line >= 1 AND end_line >= start_line),
  CHECK (doc_date IS NULL OR length(doc_date) = 10),
  CHECK (doc_date_source IS NULL OR doc_date_source IN ('path_day','path_month','heading'))
);

CREATE TABLE meta (
  key   TEXT PRIMARY KEY,
  value TEXT
);

3つの制約が守っていること

各カラムが、誰のどの機能を支えているか

「何を入れるか」だけでなく「これが無いと何ができなくなるか」を併記する。使われていないカラムは、そう書く。

3本のインデックスが、21ms を 0.35ms にする

CREATE INDEX idx_chunks_path     ON chunks(path);
CREATE INDEX idx_chunks_domain   ON chunks(domain);
CREATE INDEX idx_chunks_doc_date ON chunks(doc_date);

meta テーブル — 8つのキー

このジョブの失敗は、ほとんどがエラーを出さない

索引は「検索結果が少し減る」という形でしか壊れないので、気づくための仕組みを設計に埋め込んでおかないと、壊れたことが永遠に分からない。把握している箇所を列挙する。

現時点での既知の不整合

文書化された規約と実装が一致していない箇所が1つある。整合していないこと自体は無害だが、規約を根拠に判断すると誤る。