Qdrant Hybrid Search Combining
QdrantOfficialPublished by Qdrant
- Skill
- Tool integration
- Data and AI
- Apache-2.0
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This guide provides best practices for combining ranked candidate lists from parallel search prefetches. It covers standard fusion methods like Reciprocal Rank Fusion (RRF) and Distribution-Based Score Fusion (DBSF), as well as advanced custom fusion techniques using formula queries. The content emphasizes the importance of empirical tuning over arbitrary weight selection and provides a structured approach to optimizing hybrid search performance.
What it does
- Explains how to use RRF for rank-based fusion when scores are on incomparable scales.
- Details the use of DBSF for normalizing score distributions before fusion.
- Provides instructions for implementing custom fusion logic using formula queries and payload metadata.
- Outlines a systematic tuning order for RRF parameters and weights.
- Describes advanced fusion techniques using vector representations and late interaction models.
- Lists common pitfalls to avoid when configuring hybrid search pipelines.
When to use it
- When you need to combine results from multiple search strategies like BM25 and dense embeddings.
- When you need to incorporate payload metadata like recency or popularity into your ranking.
- When default fusion settings are not producing optimal search relevance.
- When you need to tune fusion parameters based on specific dataset characteristics.
- When you are ready to trade compute resources for higher precision ranking.
Advantages
- Provides a clear, prioritized workflow for tuning hybrid search.
- Offers multiple approaches ranging from simple rank-based fusion to complex custom formulas.
- Includes specific guidance on handling score distributions and normalization.
- Helps avoid common mistakes like using linear weighted fusion on incomparable scales.
Usage examples
- “How do I combine sparse and dense search results?”
- The guide recommends starting with RRF for incomparable scales or DBSF for normalized score distributions, emphasizing comparative testing on your own labels.
- “How do I tune RRF parameters?”
- It suggests settling on a k value first, then sweeping weights at that k, and validating the results on held-out queries.
- “Can I use payload fields in my fusion logic?”
- Yes, you can use formula queries to access both prefetch scores and payload field values to implement custom ranking logic.
Install
Download the skill as a ZIP:
https://autogineer.com/agent-skills/qdrant/qdrant-hybrid-search-combining/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip qdrant-hybrid-search-combining.zip -d .agents/skills
Documentation by Qdrant
Combining Prefetch Results
The outer query fuses ranked candidate lists from all parallel prefetches into one ranked list of results. Fusion methods differ in whether they use rank, score or directly vector representations of candidates (their similarity to the outer query) and whether final score incorporates payload metadata. All methods support flat (one fusion step) and nested (multi-stage) prefetch structures.
Tune in this order, cheapest first: confirm fusion beats each prefetch alone on your labels, compare Qdrant's default RRF vs DBSF, if tuning RRF: settle k, then sweep weights at that k, and validate on held-out queries. A weight pair is only valid for the k it was tuned with Tune in this order
Scores Are Not Comparable Across Prefetches & You Want Some Easy Baseline
Use when: searches produce scores on different scales, like BM25 and cosine on dense embeddings.
RRF
RRF (Reciprocal Rank Fusion): rank-based, ignores scores magnitude.
Start with RRF at Qdrant's defaults,
k=2and equal weights.Tune
kto control rank sensitivity in RRF fusion, choosing the value from your labels Use labels to choose akrange.Add per-prefetch weights when one search should dominate, using Weighted RRF. Weights should be customized per collection and retrievers' score distributions. Tune weights last.
DBSF
DBSF (Distribution-Based Score Fusion): normalizes score distributions per prefetch before fusing them, for that, instead of min-max, uses mean +- 3 deviations on prefetched list of scores. Avoid relying on resulting absolute scores, as scores in DBSF are normalized per prefetch (aka per a retrieved list of search results), and might be uncomparable across queries.
DBSF has no parameters to tune, so compare it before hand-tuning RRF
kand weights. Confirm on your own labels Compare RRF and DBSF on your labels
Need Custom Fusion
Use when: recency, popularity or other payload values should affect the merged ranking alongside candidate scores or you need a custom fusion.
With formula query, access score of each prefetch and, if desired, payload field values.
If you want to implement custom fusion on score of each prefetch:
Use decay or any other available expressions for normalizing score distributions before fusing them.
Parameters of these expressions should be based on the collection & retriever score distributions (for example, adjusting these parameters on a subsample of real queries).
Formula query is unable to provide ranks for custom fusions
When using FormulaQuery over multiple prefetches (e.g. per-representation weighting):
$score[i]indexes prefetches in declaration order. Reordering theprefetch=list silently shifts which weight applies to which retriever.Provide
defaultsfor every$score[i]so the formula still evaluates for candidates that surfaced from only a subset of prefetches.On Qdrant 1.19.1 or newer,
maxandminexpressions take the best or worst of several$score[i](for example, keep each point's best score across per-field BM25 prefetches), cap a boost (min(cap, boost)), or clamp a value withmax(lo, min(hi, x)). A point absent from a prefetch has$score[i]of0.0, which winsmaxover negative scores andminover positive ones, so setdefaults(keys include the$, placed besideformula, never inside it) to a value outside the expected score range such as-1e30formaxor1e30forminMax and min.On 1.19.1 or newer,
acoshsupports exact geodesic-distance rescoring for hyperbolic embeddings (Lorentz model withDotdistance,acosh(-$score), negated so closest ranks first). The input must be at least 1 Hyperbolic distance.Start with RRF when scores are on incomparable scales (e.g. BM25 + cosine). Reach for
FormulaQueryonly when explicit per-representation weighting or payload-driven boosts are required, and normalize each$score[i](decay or min-max on a sampled distribution) before combining linearly.
Need Good Ranking of Fused Candidates and Ready To Spend More Resources
Use when: you want to use similarity between query and candidates' vector representations as the prefetches combiner and simultaneously ranker. More resource heavy than score/rank based fusions, but might be necessary due to use case requirements or need in a high top-K precision of results (when parallel prefetches have overall a good recall of retrieved candidates).
More candidates only help if the ranker can use them. Deeper prefetches can raise the best possible score
You can use any type of vector as an outer query over the prefetches, to perform the fusion on the server-side in one QueryAPI request: sparse, dense, multivector. For that, same type of vector representations for documents need to be stored as named vectors per point.
Instead of using client-side fusion through cross-encoders, a popular option is Late interaction models-based fusion, through reranking on multivectors (e.g. ColBERT for text, ColPali and ColQwen for images).
Most precise but highest compute/resource usage.
Configure multivectors used for fusion through reranking with HNSW disabled like in Hybrid Search with Reranking tutorial.
What NOT to Do
Use linear weighted fusion on incomparable score ranges. Why not.
Use "vibe" defined weights in weighted RRF. Weights should be fine-tuned per dataset and retrieval pipelines.
Pick any fusion type without comparative experiments.
Use late interaction multivectors for fusion without evaluating cheaper analogues, for example, MUVERA. More in multi-vector Qdrant search course
Files
- ATTRIBUTION.mdAdded by AutoGineer914 B
- LICENSELicence file added by AutoGineer11.1 KiB
- SKILL.md7.4 KiB
SKILL.md
Combining Prefetch Results
The outer query fuses ranked candidate lists from all parallel prefetches into one ranked list of results. Fusion methods differ in whether they use rank, score or directly vector representations of candidates (their similarity to the outer query) and whether final score incorporates payload metadata. All methods support flat (one fusion step) and nested (multi-stage) prefetch structures.
Tune in this order, cheapest first: confirm fusion beats each prefetch alone on your labels, compare Qdrant's default RRF vs DBSF, if tuning RRF: settle k, then sweep weights at that k, and validate on held-out queries. A weight pair is only valid for the k it was tuned with Tune in this order
Scores Are Not Comparable Across Prefetches & You Want Some Easy Baseline
Use when: searches produce scores on different scales, like BM25 and cosine on dense embeddings.
RRF
RRF (Reciprocal Rank Fusion): rank-based, ignores scores magnitude.
Start with RRF at Qdrant's defaults,
k=2and equal weights.Tune
kto control rank sensitivity in RRF fusion, choosing the value from your labels Use labels to choose akrange.Add per-prefetch weights when one search should dominate, using Weighted RRF. Weights should be customized per collection and retrievers' score distributions. Tune weights last.
DBSF
DBSF (Distribution-Based Score Fusion): normalizes score distributions per prefetch before fusing them, for that, instead of min-max, uses mean +- 3 deviations on prefetched list of scores. Avoid relying on resulting absolute scores, as scores in DBSF are normalized per prefetch (aka per a retrieved list of search results), and might be uncomparable across queries.
DBSF has no parameters to tune, so compare it before hand-tuning RRF
kand weights. Confirm on your own labels Compare RRF and DBSF on your labels
Need Custom Fusion
Use when: recency, popularity or other payload values should affect the merged ranking alongside candidate scores or you need a custom fusion.
With formula query, access score of each prefetch and, if desired, payload field values.
If you want to implement custom fusion on score of each prefetch:
Use decay or any other available expressions for normalizing score distributions before fusing them.
Parameters of these expressions should be based on the collection & retriever score distributions (for example, adjusting these parameters on a subsample of real queries).
Formula query is unable to provide ranks for custom fusions
When using FormulaQuery over multiple prefetches (e.g. per-representation weighting):
$score[i]indexes prefetches in declaration order. Reordering theprefetch=list silently shifts which weight applies to which retriever.Provide
defaultsfor every$score[i]so the formula still evaluates for candidates that surfaced from only a subset of prefetches.On Qdrant 1.19.1 or newer,
maxandminexpressions take the best or worst of several$score[i](for example, keep each point's best score across per-field BM25 prefetches), cap a boost (min(cap, boost)), or clamp a value withmax(lo, min(hi, x)). A point absent from a prefetch has$score[i]of0.0, which winsmaxover negative scores andminover positive ones, so setdefaults(keys include the$, placed besideformula, never inside it) to a value outside the expected score range such as-1e30formaxor1e30forminMax and min.On 1.19.1 or newer,
acoshsupports exact geodesic-distance rescoring for hyperbolic embeddings (Lorentz model withDotdistance,acosh(-$score), negated so closest ranks first). The input must be at least 1 Hyperbolic distance.Start with RRF when scores are on incomparable scales (e.g. BM25 + cosine). Reach for
FormulaQueryonly when explicit per-representation weighting or payload-driven boosts are required, and normalize each$score[i](decay or min-max on a sampled distribution) before combining linearly.
Need Good Ranking of Fused Candidates and Ready To Spend More Resources
Use when: you want to use similarity between query and candidates' vector representations as the prefetches combiner and simultaneously ranker. More resource heavy than score/rank based fusions, but might be necessary due to use case requirements or need in a high top-K precision of results (when parallel prefetches have overall a good recall of retrieved candidates).
More candidates only help if the ranker can use them. Deeper prefetches can raise the best possible score
You can use any type of vector as an outer query over the prefetches, to perform the fusion on the server-side in one QueryAPI request: sparse, dense, multivector. For that, same type of vector representations for documents need to be stored as named vectors per point.
Instead of using client-side fusion through cross-encoders, a popular option is Late interaction models-based fusion, through reranking on multivectors (e.g. ColBERT for text, ColPali and ColQwen for images).
Most precise but highest compute/resource usage.
Configure multivectors used for fusion through reranking with HNSW disabled like in Hybrid Search with Reranking tutorial.
What NOT to Do
Use linear weighted fusion on incomparable score ranges. Why not.
Use "vibe" defined weights in weighted RRF. Weights should be fine-tuned per dataset and retrieval pipelines.
Pick any fusion type without comparative experiments.
Use late interaction multivectors for fusion without evaluating cheaper analogues, for example, MUVERA. More in multi-vector Qdrant search course
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Published by
- Qdrant
- Publisher
- Qdrant (Official)
- Source
- qdrant/skills · skills/qdrant-search-quality/search-strategies/hybrid-search/combining-searches · commit 9f55f6a
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by Qdrant or Qdrant.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download qdrant-hybrid-search-combining.zip