Skip to content

PATTERN Cited by 1 source

Metadata boost at query time

Intent

Let query-time business logic (recency, priority, region, tenant tier, language) re-rank already-relevant results, without re-indexing, re-embedding, or changing the relevance-scoring pipeline — by boosting on document metadata fields declared at indexing time.

Problem

Retrieval relevance — BM25 + vector similarity, optionally fused + reranked — answers "what does the text of this document say about the query?". But production ranking needs to answer a wider question: given two equally-relevant documents, which should surface first for this caller? Examples:

  • News query → recent article first.
  • Support query → tickets flagged critical first.
  • Multi-tenant SaaS → items the current user authored first.
  • Docs search → v2+ docs over v1 deprecations.

Approaches that don't work well on their own:

  • Fold the signal into the relevance score (bake it into the embedding, the BM25 weights, or a custom scorer): requires re-indexing every time the signal changes; couples per-caller context into a corpus-level asset.
  • Post-filter (WHERE priority = 'critical'): turns a preference into a hard cut; a critical-free result set returns nothing instead of the next-best.
  • Client-side re-sort of the top-K: works at small K but interacts badly with pagination + cross-encoder reranking.

Solution

Expose query-time boost clauses over document-metadata fields as a first-class retrieval API surface, separate from the relevance scorer:

const results = await instance.search({
  query: "deployment guide",
  ai_search_options: {
    boost_by: [
      { field: "timestamp", direction: "desc" }
    ]
  }
});

Cloudflare's 2026-04-16 framing:

"Retrieval gets you relevant results, but relevance alone isn't always enough. For example, in a news search, an article from last week and an article from three years ago might both be semantically relevant to 'election results,' but most users probably want the recent one. Boosting lets you layer business logic on top of retrieval by nudging rankings based on document metadata. You can boost on timestamp (built in on every item) or any custom metadata field you define."

— (Cloudflare, 2026-04-16)

Structural properties

  • Per-query. Different callers in the same app can boost differently against the same index.
  • Composable with relevance. Runs as a ranking layer on top of retrieval + fusion + (optional) reranking, not inside them.
  • Additive, not subtractive. Documents without the boosted field are still in the result set — they just don't participate in that signal. Contrast with boost_by misread as a filter.
  • Cheap writes update the signal. Bumping a document's priority or timestamp is a metadata write; no re-embedding, no BM25 re-tokenisation.
  • Built-in fields + custom fields. In AI Search, timestamp is built into every item; any custom metadata field declared at indexing time is boostable.

When to use vs other ranking levers

Need Use
Corpus-wide relevance signal baked into the retriever Re-embed / re-tune BM25
"Documents of type X only" — hard cut Metadata filter / predicate
"Prefer recent over stale" per query Boost at query time (this pattern)
"Swap top 10 order based on deep query understanding" Cross-encoder rerank
"Fuse BM25 + vector result lists" RRF / max fusion

These compose: retrieval → fusion → metadata boost → rerank → return.

Seen in

Last updated · 200 distilled / 1,178 read