Benchmarking Search

Benchmarking Trilium's backend search

Search performance only reproduces on a real database. A synthetic fixture has uniform titles, no clones, no inherited attributes and a shallow tree, and none of the costs that dominate in practice show up. Always measure against a snapshot of a real document.

1. Snapshot a real database, read-only

Never benchmark against a live document — and never let the harness write to one.

# macOS: ~/Library/Application Support/trilium-data ; Linux: ~/.local/share/trilium-data
cd ~/Library/Application\ Support/trilium-data
sqlite3 "file:document.db?mode=ro" ".backup '/path/to/bench/document.db'"

.backup uses SQLite's backup API, so it is safe while the app is running and handles the WAL. The source is opened mode=ro and never written. A 1.9 GB document copies in about seven seconds.

The snapshot must be named document.db and sit in a directory of its own — that directory becomes TRILIUM_DATA_DIR.

2. Run the benchmark

bench-search.mts has to live under apps/server/ to run: @triliumnext/core is a workspace package that pnpm links only into apps/server/node_modules, and ESM resolves bare specifiers from the importing file's own location.

cp .claude/skills/benchmarking-search/bench-search.mts apps/server/

TRILIUM_RESOURCE_DIR=$PWD/apps/server/src \
TRILIUM_DATA_DIR=/path/to/bench \
TRILIUM_GENERAL_READONLY=true \
TRILIUM_GENERAL_NOBACKUP=true \
BENCH_ITERATIONS=40 \
  node --import tsx apps/server/bench-search.mts a t 'the quick brown fox'

rm apps/server/bench-search.mts   # when finished

It boots core exactly as apps/server/src/main.ts does, minus the HTTP server, so the code under test is the real thing.

3. Profile and attribute

BENCH_PROFILE=/tmp/a.cpuprofile ... node --import tsx apps/server/bench-search.mts a

# top functions by self time
node --import tsx .claude/skills/benchmarking-search/bench-profile.mts /tmp/a.cpuprofile 15

# who calls removeDiacritic, walking past thin wrappers
node --import tsx .claude/skills/benchmarking-search/bench-profile.mts /tmp/a.cpuprofile 8 \
  removeDiacritic "normalize,normalizeSearchText,tokenizeIntoWords"

# what NoteFlatTextExp.execute spends its time on, by callee
node --import tsx .claude/skills/benchmarking-search/bench-profile.mts /tmp/a.cpuprofile 10 \
  "children:execute@note_flat_text"

The skip list matters. removeDiacritic is called ~100% from normalize, which is called ~100% from normalizeSearchText — attributing one level up tells you nothing. Skipping those names lands the blame on code that chose to normalize.

The @file suffix on children: narrows to one implementation; execute is a method on every expression type.

4. Measurement discipline

This is the most important section. Search work in this repo has repeatedly produced plausible numbers that were wrong.

Calibrate before trusting anything. Run the same code three times. Observed on a developer machine running Trilium alongside: ±10% at 12 iterations, ±4-5% at 40. Anything smaller than the floor is unresolvable, and reporting it as a win is a mistake.

Never compare measurements taken minutes apart. The machine drifts. One change here was recorded at 189 ms, and the identical code measured 210 ms later in the same session. Always measure both arms back to back, ideally in one command.

Prefer phase timers to wall clock. They are in-process, unsampled, and immune to profiler overhead. They are not in the codebase — add them temporarily around the stages of performSearch:

const t0 = performance.now();
const noteSet = expression.execute(allNoteSet, executionContext, searchContext);
const executeMs = performance.now() - t0;
// ... same around result construction, the computeScore loop, and the sort
getLog().info(`phases: execute=${executeMs.toFixed(1)} build=${buildMs.toFixed(1)} ...`);

Then take the minimum of each phase independently across iterations — the least-contended estimate of each — rather than the phases of the best single iteration.

Phase timers catch what wall clock hides. A per-search cache keyed on `${noteId}-${parentNoteId}` showed a consistent 4-8% wall-clock improvement across every query, and the phase it targeted had gone 58.4 ms → 62.1 ms, i.e. slower. The tell: executeMs had also "improved", and the change could not possibly touch executeMs. If a phase your change cannot reach appears to move, you are reading noise.

Self time undercounts. Ranking leads by self time led to sizing one at ~23 ms when its subtree was 42.9 ms. Use children: for anything whose cost is in its callees.

Strings are the usual culprit. Almost every real win here was an allocation removed, not an algorithm improved: a template literal built per call, a Map key concatenated per lookup, String.normalize("NFD") re-run over a constant. Prefer nested maps over combined string keys — Map<parent, Map<child, V>> allocates nothing per lookup.