Engine compatibility

Feature matrix#

Notes on the matrix:

1. Partial on Elasticsearch: indexes are created without an explicit mapping, so string fields are analyzed text. Filters and facets work on numbers, booleans and dates. For a string field, filter or facet on field.keyword.
2. Listing documents by offset stops at the index's pagination.maxTotalHits on Visor (1000 unless raised) and 10,000 on Elasticsearch. A walk by cursor reads every document on every engine. Visor keeps an index's primary key filterable and sortable for that; an older Visor index past 1000 documents without them names the settings to add.
3. Hybrid search needs a vector field first: an embedders setting on Meilisearch, a float[] field with num_dim on Typesense. Without one the search runs keyword-only. A Typesense index made through the API or the dashboard gets an automatic schema with no vector field, so only a Sync definition can give it one.
4. Partial on Elasticsearch synonyms and stop words: a newer index has its own synonym set and search analyzer, which apply them on every search, the engine's own API included. An index created before they came to Elasticsearch refuses them with 400 unsupported_setting; a reindex into a new index gives it the analyzer. Typesense refuses stop words because they apply to the whole server.
5. Facets and sorting a string field on Typesense need the field in filterableAttributes or sortableAttributes. Number fields sort without it, and every field filters without it. A Typesense document id is a string: a number id is stored as its string.
6. Typesense crops with its own snippet, up to cropLength words around the match. Visor crops to 20 words by default and takes a cropLength up to 1024. On Typesense, displayedAttributes, typo settings and custom ranking rules apply to searches through /v1, not to a search sent to Typesense's own API through the single entry point. The same holds for searchableAttributes, displayedAttributes and custom ranking rules on Elasticsearch.
7. Headband does not expose geo search or aggregations on any engine yet.

Visor, your own engine and OpenSearch#

Visor is ZVN's own engine, offered in a region where a dedicated engine host runs it. Headband runs it for you, so it takes no connection config. One Visor index answers in two ranking modes, chosen per request with mode: instant (the default, typo-tolerant, for as-you-type search) and retrieval (BM25F, for longer queries). Other engines ignore mode. Visor has no vector search yet.

When you create a project, you pick its default engine and can connect your own engine (BYOE). Headband translates each API call to that engine's protocol.

OpenSearch is not supported. Headband's Elasticsearch client checks that the server identifies itself as Elasticsearch and refuses any other, OpenSearch included.

Engine and machine advisor#

The project creation flow includes a workload advisor for corpus size, traffic, and use case. Start with Meilisearch for small catalogs and docs, Typesense for autocomplete-heavy UI, and Elasticsearch for logs, very large corpora, large multi-tenant content, or advanced RAG/vector workloads. Each recommendation now includes a plan fit, deployment path, ingestion plan, and upgrade trigger so teams can move from prototype to production deliberately.

These sizes are machine sizes, not plans. A Headband dedicated engine comes in memory sizes from 512 MB (1 GB for Elasticsearch) to 32 GB.

Sizing guidance is a launch baseline, not a capacity guarantee. Benchmark real documents, filters, and p95/p99 latency targets before production rollout.

Production sizing runbook#

Repo runbook: docs/engine-machine-sizing-runbook.md keeps the same operator checklist available outside the app.