How do I index notes for compass?
Prerequisite for the search pillar of the compass tool. Indexing
reads .org-roam.db; pass --org-roam-db-sync to regenerate it
first, or sync it any other way (compass build --direct org-roam-db-sync,
M-x org-roam-db-sync in Emacs).
Question
How do I build (or refresh) the local search cache compass searches over?
Answer
Run compass.sh index. It reads org-roam.db at the repo root and
writes an FTS5 cache to .compass.db (git-ignored), updating only files
whose mtime changed:
./compass.sh index # incremental, by mtime ./compass.sh index --org-roam-db-sync # regenerate .org-roam.db first
compass search (pretty format) reports the age of both databases —
green under 1h, warning over 5h, critical over 24h — with the refresh
command to run, so a stale cache announces itself.
To discard the cache and rebuild from scratch (e.g. after large renames or an org-roam schema change):
./projects/ores.compass/compass.sh index --rebuild
Inspect what is indexed with debug:
./projects/ores.compass/compass.sh debug ./projects/ores.compass/compass.sh debug -f glossary
If .org-roam.db is missing entirely, index --org-roam-db-sync
creates it (emacs batch; packages from ./.packages).
Script
projects/ores.compass/compass.sh index → src/compass.py (cmd_index),
reading org-roam.db read-only and writing .compass.db.
Tested by
Manual smoke test. index is incremental by mtime; --rebuild forces a
full pass.
See also
- How do I search docs with compass? — query the cache this builds.
- How do I see where we are? — orientation (needs no index).