Engine Compatibility
Headband supports four engines: Meilisearch, Typesense, Elasticsearch and Visor. The same endpoints work whichever engine an index is on, but the engines do not all honor every feature: the matrix below says what each one does through the API. To run the same data on several engines, see Index Into More Than One Engine.
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.
Small
1-2 vCPU / 1-4 GB RAM for dev, beta, and small production indexes. Direct writes are fine; backfill in small chunks.
Medium
4-8 vCPU / 8-16 GB RAM when facets, filters, or autocomplete traffic rise. Add queues and replayable sync jobs.
Cluster
BYOE clusters with replicas for 1M+ docs, high QPS, or log data. A Headband dedicated engine is one node. Benchmark before committing SLOs.
When to upgrade
Move up when p95 search latency crosses 200-250ms, autocomplete exceeds 100ms, indexing competes with live search, reindex windows exceed your rollout budget, or restore/snapshot time exceeds your recovery objective.
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
1. Pick the retrieval job
Catalog, autocomplete, docs/RAG, logs, or multi-tenant content. Do not choose a machine before the workload is named.
2. Start with a tier
Small: 1-2 vCPU. Medium: 4 vCPU / 8 GB. Large: 8+ vCPU / replicas. Cluster: benchmarked BYOE cluster.
3. Validate with traffic
Test filters, facets, sort, pagination, p95/p99 latency, zero-result rate, and A/B/C variants using real documents.
Repo runbook: docs/engine-machine-sizing-runbook.md keeps the same operator checklist available outside the app.
Feature Matrix
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.
Listing documents by offset stops at 1000 on Visor 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.
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.
Elasticsearch refuses synonyms and stop words with 400 unsupported_setting, as it refuses the attribute lists and pagination: its search would not apply them. Typesense refuses stop words because they apply to the whole server.
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.
Headband does not expose geo search or aggregations on any engine yet.
CORS: The /v1 API supports CORS for browser-based usage. Search keys are safe to use in frontend applications. Admin keys should only be used server-side.