zetl

ADR-002: Search Without Index

Status: Accepted

Context

zetl needs full-text content search across vault files (see Search Command). The question is whether to build an inverted index (like Lucene/tantivy) or scan files directly on each query.

Decision

Use index-free scanning — read and search files directly on each query.

Rationale

  • Simplicity — no index build step, no index format to maintain, no index invalidation logic beyond what architecture/Cache already handles
  • Correctness — results always reflect the current file contents; no stale index entries
  • Acceptable performance — scanning 10,000 files completes in under 2 seconds on commodity hardware (see Performance)
  • Consistency — zetl already has an mtime-based cache for the link graph; adding a second indexing system increases complexity disproportionately

Trade-offs

  • Slower than an inverted index for very large vaults (>50k files)
  • No ranking or relevance scoring — matches are returned in file order
  • Regex search performance depends on pattern complexity

Mitigation

The --path filter (from Agent Ergonomics) lets users restrict search to a subdirectory, which reduces scan scope. The --limit flag bounds result size.

See also: Search Command, Performance, SPEC-002 Full-Text Search

Backlinks