Spike: Orama

[enf0rc3]

Spike 2 of 2 for the search engine bake-off. Branched off #3369, so that PR's commit is in this diff. Pagefind is #3371.

What it does

Replaces the hand-rolled search.json engine with Orama, behind the SearchEngine seam from #3369. Body text is searchable for the first time.

The corpus is the markdown llm-md-emitter already writes into dist/docs/, so there is no second extraction pipeline to keep in step — the emitter runs the same eligibility predicate search uses, so redirect stubs and navSearch: false pages are gone before this sees them.

The whole index is downloaded and restored into memory once, in a worker, and every query after that costs nothing. Restore is CPU-bound and would freeze the page while the overlay is open, which is why it is off the main thread.

Deletes 645 lines of custom search code: a Porter stemmer, a synonym map, the string helpers and the legacy engine.

Results

Measured through the search overlay on the deployed environment, 102 queries, against expected URLs written before the run. Fast 4G with a 4× CPU throttle.

	Legacy	Orama
Index on the wire (brotli)	0.35 MB	0.66 MB
Parsed per page load	1.74 MB	5.33 MB
Success@5	76%	78%
Success@1	58%	50%
Natural-language queries	67%	87%
Typo queries	42%	58%
While still typing	49%	63%
Warm search	276 ms	256 ms
Return visit	232 ms	201 ms

Better top-five recall than the engine it replaces, and substantially better at natural language, misspellings, and partial queries — which is most of the time the panel is open, since the overlay searches on every keystroke. Legacy still leads rank-one and MRR.

Cold start

The first search of a visit measures 5714 ms on this environment, because Azure static website endpoints serve blobs uncompressed and the raw index is 5.33 MB. Front Door returns Content-Encoding: br for the /docs/ route, and with bandwidth scaled for that ratio the same search is ~1807 ms.

Warming the index on page load rather than on overlay open takes it to 275 ms with two seconds of reading time first. That is not done here — #3371 added an eager flag to the seam for it, and this branch should use it before merging.

The index has to stay under 8 MB. Front Door only compresses responses between 1 KB and 8 MB. At 5.33 MB there is headroom, but crossing it would stop compression silently and return the cold start to ~5.7 s. Worth a build-time assertion alongside the existing page-count check.

Configuration that matters

Four settings that are easy to get wrong and were, at first:

• The worker must create its database with the same tokenizer the index was built with. load restores the data but the tokenizer comes from create, so building with the English stemmer and restoring without it compares unstemmed query terms against stemmed index terms. Searching variables matched 5 pages instead of 321 and no typo matched at all, while search kept returning results throughout.
• Stop words are not on by default. Orama's tokenizer defaults stopWords to an empty list, so how, do and 178 others were live search terms. The list ships separately as @orama/stopwords.
• sort: { enabled: false } — nothing here sorts, and the sort store was 2.69 MB of the index.
• The stored body is trimmed to 200 characters after save(). The inverted index keeps every term; this is only the copy the result excerpt is cut from.

Together the last two took the index from 11.43 MB to 5.33 MB with rankings unchanged.

Notes

• @orama/plugin-data-persistence cannot be bundled for a browser worker — it reaches for Node's filesystem and buffers, and the worker dies on import with Class extends value undefined. Core save/load do the same job and are what this uses.
• Facet counts come from Orama's own facets rather than being counted from returned hits, which capped them at the worker's result limit.
• Orama returns whole documents rather than excerpts, so the result row cuts its own window around the first matched term.
• Typo tolerance works, but only once the tokenizer matches at both ends. It is worth 16 points on the typo bucket.
• Plausible.astro still listens for a searched event that nothing fires. Left for whichever spike merges.

🤖 Generated with Claude Code

[team-marketing-branch-protections]

Pull request environment is available at https://stoctodocspr3372.z22.web.core.windows.net.

You can view the ephemeral environment status in Octopus Deploy.

This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity.

[enf0rc3]

Correction and staging results

The 2.4 MB gzipped figure in the description is not achievable on this hosting. Azure Blob static website hosting does no on-the-fly compression — requesting Accept-Encoding: gzip returns the full 11,989,438 bytes with no Content-Encoding header. Verified on this PR's own ephemeral site:

curl -H "Accept-Encoding: gzip" .../docs/search-index.json
200  wire=11989438b  type=[application/json]   # no Content-Encoding

Nothing on that host is compressed, Pagefind's assets included. So the real wire cost for Orama is 11.4 MB, not 2.4 MB. Getting the compressed figure would need the microsite-deployment pipeline to pre-compress and set Content-Encoding at upload. Production sits behind Front Door which can compress, but 11.4 MB is above its documented 8 MB ceiling, so it probably would not help there either — worth confirming before relying on it.

It works, and on a fast connection it feels fine

https://stoctodocspr3372.z22.web.core.windows.net/docs

tentacle → 200 results, All 200 / Docs 151 / API 7 / CLI 42. Cold search 2.16s, which is actually a shade faster than Pagefind's 2.31s on the same connection. Results are relative and stay on staging.

That is the honest picture at ~47 Mbps: the download is 2 seconds and you would not notice. The gap is entirely about what happens below that.

Connection	Orama 11.4 MB	Pagefind 278 KB
47 Mbps (measured)	2.0s	~0.05s
10 Mbps (4G)	9.6s	0.2s
1.6 Mbps (Fast 3G)	60s	1.4s

Download time only; arithmetic from the measured wire sizes, not measured directly.

Recommendation

Close this in favour of #3371. Payload was always the deciding axis and this makes it worse, not better — every visitor who searches pays 11.4 MB uncompressed, against 1.86 MB today. Typo tolerance, the one thing that could have justified the cost, returns nothing for kuberntes.

Worth keeping from this spike if Pagefind is ever revisited: reusing llm-md-emitter's output as the corpus worked cleanly and needed no second extraction pipeline, and Orama ranked target tag and RBAC better than Pagefind does.