Search & retrieval

Hybrid search with rank fusion

Combines keyword relevance and semantic similarity into one ranked list on the server, so the client does not have to merge two score scales.

BetaEngine edition 5f8ea3af

What it does

POST /v1/hybrid runs a BM25 query and a vector query over the same corpus and fuses the two ranked lists with weighted reciprocal-rank fusion. Either leg can be omitted. The response keeps each leg score and rank next to the fused score so a ranking can be inspected.

How it works

BM25 scores and cosine similarities live on different scales, so the engine fuses ranks rather than scores. Each leg contributes weight divided by (rrf_k plus rank) for every candidate it returns, the contributions add up per entity, and ties break by id so the order is stable. Defaults are bm25_weight 1, vector_weight 1 and rrf_k 60. Weights must be finite and non-negative with at least one above zero, and rrf_k must be positive.

The request needs q, vector or both. The BM25 leg uses the same index as /v1/search. The vector leg uses the same scan as /v1/vector. top_k is clamped to 1 through 200, and a clamp is reported in an x-kynetra-effective-limit response header. candidate_k, the pool each leg contributes, defaults to the larger of four times top_k and 50 and is clamped between top_k and 1,000.

kind is pushed into the BM25 leg, and kind plus filter go to the vector leg as a pre-filter. Every fused hit is then checked against the filter again before truncation, with a fallible read: a store read error is an error, never a silently shorter list. While the engine is fenced for recovery, every leg refuses and the route returns the typed 503.

Each hit carries id, kind, the fused score, bm25_score, vector_score, bm25_rank and vector_rank. A leg that did not return an entity leaves its fields null, which makes it easy to see why something ranked where it did.

Where you reach it

  • HTTPPOST /v1/hybrid { q, vector, top_k, candidate_k, kind, filter, bm25_weight, vector_weight, rrf_k }
  • SDKSearchClient.hybrid in the TypeScript and Python client sources

Example

Keyword and semantic query fused, vector leg weighted higherbash
curl -s "$KYNETRA_URL/v1/hybrid" \
  -H "Authorization: Bearer $KYNETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "waterproof trail shoes",
    "vector": [0.12, 0.31, -0.08, 0.44],
    "top_k": 10,
    "kind": "product",
    "bm25_weight": 1.0,
    "vector_weight": 2.0
  }'

# each hit: id, kind, score, bm25_score, vector_score, bm25_rank, vector_rank

Limits

  • The vector leg is the exact scan unless an approximate index was built through the engine library, so hybrid cost grows with the number of embeddings. No latency figure is published for the fused route.
  • Fusion works on ranks and ignores raw scores. There is no learned or per-query weighting; the weights are what the caller sends.
  • Reranking policies are a separate capability and are not applied to this route automatically.
  • The response does not say how many matches were cut off by top_k.
  • The route accepts service credentials: the instance key or a project service key.

Evidence

  • On this siteHTTP API reference
  • TestsEngine and HTTP tests cover rank fusion for entities present in both lists, pre-filter handling after fusion, refusal on every leg while the engine is fenced, store-read errors during the post-check, and the top_k clamp header

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to talk through the limits above against your own workload.