Hybrid search

Combine keyword search with vector similarity in a single request. Pass a pre-computed embedding vector alongside your text query, and the engine blends both signals.

Headband does not generate embeddings: compute the vector with your own model (OpenAI, Cohere and so on). The request is the same on Meilisearch, Typesense and Elasticsearch, but each index needs a vector field first: see Vector fields per engine.

POST/v1/hybrid-search

Unified keyword + vector search. Falls back to keyword-only when no vector is provided.

Auth: admin or search key
Returns: 200

Request body

{
  "index": "products",
  "q": "wireless headphones",
  "vector": [0.12, -0.34, 0.56, ...],
  "semanticRatio": 0.7,
  "limit": 20,
  "filter": "price < 200"
}

Response

{
  "hits": [
    {
      "id": "42",
      "title": "Wireless headphones",
      "_scoring": {
        "keyword": 11.2,
        "semantic": 0.91,
        "combined": 0.0328
      }
    }
  ],
  "query": "wireless headphones",
  "processingTimeMs": 18,
  "estimatedTotalHits": 156,
  "fallback": false
}

Parameter	Type	Default	Description
`index` · string	string	Required	Index UID to search
`q` · string	string	""	Keyword query string
`vector` · number[]	number[]	–	Pre-computed embedding vector. Omit for keyword-only search
`semanticRatio` · number	number	–	Balance between keyword (0) and vector (1) results. Must be 0-1
`limit` · number	number	20	Maximum hits to return
`filter` · string	string	–	Filter expression in engine syntax

Keyword-only fallback

When the index has no vector field, the search runs keyword-only and still answers 200, with "fallback": true in the response. On Typesense and Elasticsearch it does the same when you send no vector. If hybrid search seems to change nothing, check fallback before tuning semanticRatio.

Vector fields per engine

Engine	What the index needs
Meilisearch	An `embedders` setting.
Typesense	A `float[]` field with `num_dim`. A Typesense index made through the API or the dashboard has an automatic schema with no vector field, and Typesense takes no schema change after that, so only a Sync definition can give it one.
Elasticsearch	A `dense_vector` field. See Elasticsearch vectors.
Visor	No vector search yet: on a Visor index the request runs keyword-only and the response carries `fallback: true`.

What _scoring means

Each hit carries _scoring with three numbers. combined is the score the hits are ranked by. keyword and semantic are the two parts, but only where the engine reports them. A part the engine does not report is 0, so a 0 does not mean the hit failed to match.

Elasticsearch, with a vector field: keyword is the raw BM25 score, semantic the kNN score, and combined the reciprocal rank fusion score Headband computes from the two lists.
Typesense, with a vector field: keyword is text_match, semantic is 1 minus the vector distance, and combined the fusion score when Typesense reports one.
Meilisearch, with an embedder: only combined is set, to Meilisearch's ranking score (0 to 1). keyword and semantic are always 0, because Meilisearch does not report the two parts.
Keyword-only (fallback: true): semantic is 0 and keyword equals combined.

The scales differ by engine, so compare scores within one index only, never across engines.

Elasticsearch vectors

Headband creates an Elasticsearch index with dynamic mapping, and its settings API has no mapping field. A float array sent in a document then becomes a plain float field, not a vector, and hybrid search keeps answering fallback: true. Add the dense_vector field on the engine itself, through its dedicated engine endpoint, before any document carries that field:

terminal

export ADMIN_KEY="hb_adm_..."

# 1. The engine's endpoint, and the
# index's name on it (engineIndexUid)
headband instances list
headband indexes list

# 2. Map the vector field. dims is your
# embedding model's size.
HOST="<id>.ewr1.search.headband.dev"
INDEX="<engineIndexUid>"
curl -X PUT \
  "https://$HOST/$INDEX/_mapping" \
  -H "Authorization: ApiKey $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "embedding": {
        "type": "dense_vector",
        "dims": 1536,
        "index": true,
        "similarity": "cosine"
      }
    }
  }'

# 3. Add documents with an "embedding"
# array, then search with a vector
API=https://api.headband.dev/v1
curl -X POST \
  "$API/hybrid-search" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "products",
    "q": "wireless headphones",
    "vector": [0.12,-0.34,...],
    "semanticRatio": 0.5
  }'

Use an admin key on the engine endpoint: an organization-wide one, or a project key of the index's branch. A search key can only search there, so it cannot change a mapping.
The index's name on Elasticsearch is lower-cased, such as hbp_<project id>_products. Copy it from engineIndexUid rather than building it from the uid.
Map the field first. Once a document has put a float array under that name, the field is a number field and Elasticsearch refuses to change it (mapper [embedding] cannot be changed from type [float]). Then use a new field name, or delete and re-create the index.
With the field mapped, the response carries fallback: false and each hit carries its keyword and semantic scores.
headband indexes list shows instanceId and engineIndexUid for an index on a dedicated engine. An index on your own Elasticsearch cluster (a custom engine config) takes the same mapping on that cluster directly.

Vector fields per engine#

What _scoring means#

Elasticsearch vectors#

Vector fields per engine

What _scoring means

Elasticsearch vectors