Back to blog
Tutorials

turbopuffer hybrid search: BM25 + vector with multi-queries and rank fusion

A turbopuffer hybrid search is one multi-query with a BM25 leg and a vector leg, fused server side with rerank_by RRF. The schema, the query, filters on both legs, and when to fuse in your own code.

Abhilash B13 min read
#turbopuffer#hybrid search#bm25#rrf#vector search

A turbopuffer hybrid search is one multi-query request: a subquery that ranks by ["content", "BM25", q], a subquery that ranks by ["vector", "ANN", v], and rerank_by: ["RRF"] on the outer request, which fuses the two lists by rank with a default rank_constant of 60. Use that server-side fusion whenever both legs search the same namespace. Fuse in your own code only when the legs span namespaces, or when you need each leg's ranks for evaluation.

Everything here was checked against turbopuffer's documentation as of October 2026, mainly the hybrid search guide and the query reference. We had no account to run against, so the API code is written to the documented Python SDK (turbopuffer 3.1.0 on PyPI) and labelled illustrative. The client-side RRF function is plain Python, and its output below is from a real run on illustrative ranked lists.

Enabling BM25 full-text search on an attribute

BM25 works on string and []string attributes that have full_text_search set in the schema. A boolean true takes the defaults. An object lets you pin the analysis, and the schema reference lists these fields:

FieldDefaultWhat it does
tokenizerword_v4Splits text into tokens. The default "is periodically upgraded for new namespaces"
languageenglishDrives stemming and stopwords. 18 languages are listed
stemmingfalseLanguage-specific stemming
remove_stopwordsfalseDrops common words for language. Not available for arabic, greek, romanian, tamil or turkish
case_sensitivefalseCase-insensitive matching by default
ascii_foldingfalseMaps à to a after stemming and stopword removal
max_token_length39Tokens longer than this many bytes are dropped (range 1 to 254)
k1, b, k31.2, 0.75, 8.0BM25 term saturation, length normalization and query-term saturation

Two defaults deserve a decision on day one. Stemming is off, so a query for throttling will not match a document that says throttled. And the tokenizer default can change for namespaces created later, which means a tenant created next quarter could tokenize differently from one created today. Set tokenizer explicitly so every namespace behaves the same.

max_token_length: 39 drops longer tokens silently, so long identifiers and some URLs never become searchable. The word_v4 and word_v3 tokenizers follow Unicode UAX #29 word segmentation. Under those rules an underscore joins letters and digits, so ERR_429 should stay one token, while word_v2 discards non-alphanumeric codepoints and would split it. We could not run this, so if your users search for codes, confirm it on a test namespace with a ContainsAllTokens filter before you rely on it.

Billing follows the index count. Setting full_text_search makes the attribute non-filterable unless you also set filterable: true, and an attribute with both is billed at 200% of its logical size, per the write docs.

# Illustrative: written to the documented Python SDK, not run against a live account.
import turbopuffer

tpuf = turbopuffer.Turbopuffer(region="gcp-us-central1")  # reads TURBOPUFFER_API_KEY
ns = tpuf.namespace("prod.docs.t-4f9c2e1a")

FTS = {
    "tokenizer": "word_v4",   # pinned: the default is upgraded over time
    "language": "english",
    "stemming": True,
    "remove_stopwords": True,
}
SCHEMA = {
    "vector": {"type": "[768]f16", "ann": True},
    "title": {"type": "string", "full_text_search": FTS},
    "content": {"type": "string", "full_text_search": FTS},
    "acl_groups": "[]uuid",
    "is_public": "bool",
}

ns.write(
    upsert_rows=[
        {
            "id": "err-429",
            "vector": embed("ERR_429: Too many requests ..."),  # your 768-d model
            "title": "ERR_429: Too many requests",
            "content": "The API returns ERR_429 when a key exceeds its rate limit ...",
            "acl_groups": [],
            "is_public": True,
        },
    ],
    distance_metric="cosine_distance",
    schema=SCHEMA,
)

Changing FTS parameters later is allowed in place, but the index is rebuilt in the background and queries keep using the old settings until it finishes. Enabling full_text_search on an existing attribute returns HTTP 409 to BM25 queries until the new index is built. If you would rather not run an embedding model, the vector leg can use native embedding with ["content", "ANN", ["Embed", q]] once content has embed set in the schema. The rest of this post works the same either way.

Several text fields can share one BM25 leg. rank_by combines clauses with Sum or Max and scales them with Product, so ["Sum", [["Product", 2, ["title", "BM25", q]], ["content", "BM25", q]]] doubles title hits. For type-ahead, pass {"last_as_prefix": true} as a fourth element, and note that the docs score prefix matches as a flat 1.0.

The turbopuffer hybrid search query

A multi-query sends up to 16 subqueries to one namespace in one request. The query docs state that "all reads in a multi-query are executed against the same consistent snapshot of the database", so a write landing between your BM25 and vector calls cannot make the two legs disagree about which documents exist. They also say multi-queries "offer better performance than issuing independent queries to the same namespace". The outer request takes rerank_by, limit, consistency and vector_encoding. Everything else goes on each subquery.

# Illustrative: hybrid query with server-side RRF.
q = "why is the API throttling my requests"

resp = ns.multi_query(
    queries=[
        {"rank_by": ("vector", "ANN", embed(q)), "limit": 50,
         "include_attributes": ["title"]},
        {"rank_by": ("Sum", (("Product", 2, ("title", "BM25", q)),
                             ("content", "BM25", q))),
         "limit": 50, "include_attributes": ["title"]},
    ],
    rerank_by=("RRF",),  # or ("RRF", {"rank_constant": 60, "weights": [1, 1]})
    limit=10,            # caps the fused list
)
fused = resp.results[0].rows  # one combined list; $dist holds the RRF score

The same request over HTTP, as POST /v2/namespaces/:namespace/query:

{
  "queries": [
    {"rank_by": ["vector", "ANN", [0.013, -0.072, "..."]], "limit": 50},
    {"rank_by": ["content", "BM25", "why is the API throttling my requests"], "limit": 50}
  ],
  "rerank_by": ["RRF", {"rank_constant": 60, "weights": [1, 1]}],
  "limit": 10
}

Per the docs, the fused score is the sum of weight / (rank_constant + rank) over the subquery lists, with rank starting at 1. rank_constant defaults to 60 and takes any integer above zero. weights needs exactly one value per subquery, in queries order, each above zero. Per-subquery weights shipped in July 2026, according to the changelog. RRF needs at least two subqueries and does not work with aggregations. The response is a single list in results[0], and $dist holds the RRF score in place of the vector distance or BM25 score.

flowchart LR
  Q(["User query"]) --> E["Embed query<br/>or use Embed in rank_by"]
  Q --> B["Subquery 2: BM25<br/>title x2 + content, limit 50"]
  E --> A["Subquery 1: ANN<br/>vector, limit 50"]
  A --> S{"Same snapshot"}
  B --> S
  S --> R["rerank_by RRF<br/>weight / (60 + rank)"]
  R --> L(["Outer limit 10<br/>results[0].rows"])

One documentation inconsistency to know about: the concepts page still says to "combine results client-side using techniques like reciprocal-rank fusion", while the hybrid guide and query reference document server-side RRF. The query reference is the more specific source, and the older advice still applies across namespaces, as the client-side section below shows.

Server-side or client-side fusion

SituationFuse whereWhy
Both legs on one namespaceServer, rerank_by: ["RRF"]One list back, capped by the outer limit
Tenant namespace plus a shared public namespaceClientA multi-query targets one namespace
Building an eval set or debugging a rankingClient, or server plus compute_attributesYou need each leg's rank or score
Fusion other than RRF, or a custom tie-breakClientServer-side offers RRF or a reranking model
Reranking with a model afterwardsServer, rerank_by with a model objectIt scores the deduplicated union directly

On the last row: model reranking uses the same field, rerank_by: {"model": ..., "attribute": ..., "query": ...}, so a request picks RRF or a model. The September 2026 changelog lists native reranking as a private beta.

Client-side RRF in ten lines

This function reproduces the documented formula, so it gives the same scores as the server for the same lists. It keeps ids as opaque keys, which matters when two namespaces contain the same id.

from collections import defaultdict

def rrf(ranked_lists, weights=None, rank_constant=60, limit=10):
    """Same formula as turbopuffer's rerank_by ["RRF"]: sum of weight / (rank_constant + rank), rank from 1."""
    weights = weights or [1.0] * len(ranked_lists)
    if len(weights) != len(ranked_lists):
        raise ValueError("one weight per ranked list")
    scores = defaultdict(float)
    for ids, w in zip(ranked_lists, weights):
        for rank, doc_id in enumerate(ids, start=1):
            scores[doc_id] += w / (rank_constant + rank)
    return sorted(scores.items(), key=lambda kv: (-kv[1], str(kv[0])))[:limit]

We ran it on Python 3.13.6 with two illustrative lists for the throttling query. The vector leg returned eight help-centre articles. The BM25 leg returned five, because the docs say "documents with a score of zero are excluded from results", so BM25 only returns documents that share a token with the query.

vector = ["rate-limits", "err-429", "traffic-spikes", "retries-backoff",
          "rest-api", "err-401", "quotas", "status-page"]
bm25 = ["err-429", "rest-api", "rate-limits", "err-401", "request-refund"]
k=60, weights [1, 1]          k=60, weights [2, 1]          k=10, weights [1, 1]
  1. err-429          0.03252   1. rate-limits      0.04866   1. err-429          0.17424
  2. rate-limits      0.03227   2. err-429          0.04865   2. rate-limits      0.16783
  3. rest-api         0.03151   3. rest-api         0.04690   3. rest-api         0.15000
  4. err-401          0.03078   4. err-401          0.04593   4. err-401          0.13393
  5. traffic-spikes   0.01587   5. traffic-spikes   0.03175   5. traffic-spikes   0.07692
  6. retries-backoff  0.01562   6. retries-backoff  0.03125   6. retries-backoff  0.07143

The arithmetic for first place at the default: err-429 is second for vectors and first for BM25, so 1/62 + 1/61 = 0.03252. Doubling the vector weight moves rate-limits (vector first, BM25 third) to the top by 0.00001, because at k = 60 neighbouring ranks are worth almost the same. Weights at that constant mostly break near ties. Dropping rank_constant to 10 widens the gaps between positions without changing this order. Every document found by both legs beats every document found by one, which is the usual RRF behaviour and the reason how RRF and score normalization differ matters for queries where one leg is right and the other is noise. That post walks through the math, and the hybrid search playground lets you move window size and fusion settings and watch the ranking change.

Filters on both legs

A multi-query has no outer filters. Each subquery carries its own, which is flexible and also the easiest way to leak a document: put the ACL filter on the vector leg, forget it on the BM25 leg, and RRF will happily fuse in a document the user should not see. Build every leg from one function that owns the filter.

# Illustrative: one permission filter, applied to every leg.
def hybrid(ns, q, vec, user_groups, k=10, window=50, extra_bm25_filter=None):
    acl = ("Or", (("is_public", "Eq", True),
                  ("acl_groups", "ContainsAny", user_groups)))
    bm25_filter = ("And", (acl, extra_bm25_filter)) if extra_bm25_filter else acl
    return ns.multi_query(
        queries=[
            {"rank_by": ("vector", "ANN", vec), "filters": acl,
             "limit": window, "include_attributes": ["title"]},
            {"rank_by": ("content", "BM25", q), "filters": bm25_filter,
             "limit": window, "include_attributes": ["title"]},
        ],
        rerank_by=("RRF",),
        limit=k,
    ).results[0].rows

On the ANN leg, the query docs say the planner combines the attribute index with the ANN index for recall, so a selective ACL is applied during the vector search instead of after it. Phrase filters are the exception. The docs say ContainsTokenSequence is implemented as "a partial postfilter which may lead to reduced recall on ANN queries", so extra_bm25_filter is where a quoted-phrase constraint belongs. The query docs also say to "separate documents into namespaces instead of filtering where possible", and our post on turbopuffer namespace design covers where that boundary goes.

Fusing across two namespaces

With one namespace per tenant, a tenant that also searches a shared public corpus needs two multi-queries, one per namespace, sent in parallel. Ask each for its raw legs without rerank_by, then fuse all four lists at once. Fusing the four legs directly keeps each leg's rank, which fusing two pre-fused lists would throw away. Key ids by namespace.

sequenceDiagram
  participant App as Your backend
  participant T as Tenant namespace
  participant P as Public namespace
  par two requests in parallel
    App->>T: multi_query: ANN leg + BM25 leg, no rerank_by
    App->>P: multi_query: ANN leg + BM25 leg, no rerank_by
  end
  T-->>App: results[0], results[1]
  P-->>App: results[0], results[1]
  Note over App: rrf over 4 lists<br/>ids keyed as namespace/id
  App-->>App: top 10

Real output from the same function, with illustrative lists (tenant legs first):

4 legs, 2 namespaces               4 legs, tenant weight 1.5
  1. public/err-429         0.03252   1. tenant/contract-quota  0.04878
  2. tenant/contract-quota  0.03252   2. tenant/err-429-runbook 0.04840
  3. public/rate-limits     0.03227   3. public/err-429         0.03252
  4. tenant/err-429-runbook 0.03227   4. public/rate-limits     0.03227
  5. public/rest-api        0.01613   5. tenant/sso-setup       0.02419

With equal weights, exact ties are common: first and second place in one list scores the same as second and first in another, so 1/61 + 1/62 appears twice. The query docs do not specify a tie-break for server-side RRF, which is one more reason the client function sorts on id as a second key. A weight of 1.5 on the tenant legs puts the tenant's own runbook above the generic public article, which is usually what a B2B user expects. The two requests also go through separate cache paths, so a cold tenant namespace sets the latency of the whole call. Our post on turbopuffer cold start latency covers warming it at session start.

What a hybrid query costs

The pricing page bills each query for data queried, which is the namespace size with a 1.28 GB minimum, plus data returned at $0.05 per GB on Launch and Scale, as of October 2026. It does not say whether a multi-query is billed once or once per subquery. Each response carries a billing object with billable_logical_bytes_queried, so check it on your first request. Until then, the conservative reading is one query per subquery, and that is what this table uses for an illustrative 5 GB tenant namespace, 2 KB rows and one million hybrid queries.

PatternData queried, 1M queriesRows returned per queryMonthly cost at $1/PB + $0.05/GB
Server RRF, legs of 50, outer limit 102 x 5 GB = 10 PB10 (20 KB)$10 + $1 = $11
Client fusion, legs of 50 with title and content2 x 5 GB = 10 PBup to 100 (200 KB)$10 + $10 = $20
Client fusion on ids, then an id In lookup for 103 x 5 GB = 15 PBabout 10 (20 KB)$15 + $1 = $16

Under the per-subquery assumption, a hybrid query costs the same in data queried as two separate queries, so the reasons to use a multi-query are the shared snapshot and one round trip. The difference between the rows is data returned: server-side RRF only returns the fused top limit, while client fusion returns both windows. The lookup row depends on namespace size, because a lookup is another query billed on the whole namespace. Returning content in the legs costs 90 extra rows x 2 KB = 180 KB, or $0.000009 per query at $0.05 per GB. One extra query costs $0.000001 per GB of namespace at $1 per PB. They break even at 9 GB, so below that (and never below the 1.28 GB floor) the ids-then-lookup pattern is cheaper, and above it returning content in the legs wins. Server-side RRF beats both whenever the legs share a namespace.

Evaluating the hybrid setup

Fusion choices should come from labelled queries. A workable loop:

  1. Collect 50 or more real queries with known relevant documents, mixing identifier lookups such as error codes with paraphrases. Hold out half.
  2. Run each leg alone, then RRF at k = 60, then any weighted variant, and record recall@10 and nDCG@10. The hybrid guide recommends a judgment list and NDCG too.
  3. Log both signals for every candidate. In each subquery, compute_attributes can return the other leg's score, such as {"bm25_score": ["content", "BM25", q]} on the ANN leg, without another round trip.
  4. Raise the leg limit and rerun. RRF only sees documents inside each window, so window size changes rankings.
  5. If one leg alone beats the fusion, fix that leg's analysis or embeddings before you tune weights.

Retrieval recall caps what an agent can answer, which is the argument in an agent is only as good as its retriever. If you are comparing engines for this workload, the turbopuffer vs Pinecone comparison covers how each handles lexical search, and Qdrant hybrid search with the Query API shows the same RRF decisions where the default constant is 2.

Our recommendation: pin the tokenizer and turn on stemming, send BM25 and ANN as one multi-query with rerank_by: ["RRF"] at the default constant, apply filters through one function that builds every leg, and only fuse client side when your legs cross namespaces.

Where we can help

We set up turbopuffer full-text schemas and hybrid queries, then build the labelled-query evaluation that decides window sizes and weights on your data. See our turbopuffer consulting service.

Advisor, Query Quotient

Abhilash B is an advisor at Query Quotient and an information retrieval and AI expert who holds patents in the field. Abhilash brings that retrieval depth to the search, RAG and agent systems Query Quotient builds for clients.

Keep reading

Building something similar?

Tell us what you are working on. In a free 30-minute call we will give you an honest view of the approach, the effort and how to measure success.