Hybrid Search - The {!hybrid} Query Parser

Hybrid Search — the {!hybrid} parser

Every Opensolr vector-enabled index runs searches through {!hybrid} — a custom Solr query parser built by Opensolr that fuses keyword relevance (BM25) and semantic relevance (vector / KNN) into a single, correctly-ranked result list. It is what makes a query like “tyre that works on both summer and winter” return all-season tyres even on a catalog that never uses those words.

The problem it solves

Keyword and vector search speak two different score languages that cannot simply be added together:

• Keyword (BM25) scores are unbounded — a single word matching a short title can score 12, 40, or higher, and the range changes with every query.
• Vector (KNN) similarity is bounded 0–1 and, with modern embedding models, sits in a narrow high band.

If you just sum them, one signal always drowns the other: a strong keyword match buries a semantically perfect result, or vice-versa. The classic Solr way of combining them (a {!bool} query) suffers from exactly this, and it makes the search-mode labels (Union, Keywords Required, …) only look like they do something. {!hybrid} fixes both problems.

How it works

1. Both signals run independently. The parser executes the keyword query and the vector query separately, each returning its own best candidates — so a result the vector missed can still be found by keywords, and vice-versa.
2. The Search Mode chooses the candidate set — for real.
   • Union — keyword hits or vector hits (broadest recall).
   • Keywords Required — must match keywords; meaning re-ranks.
   • Meaning Required — must be semantically relevant; keywords re-rank.
   • Intersection — both must match (highest precision).
3. Every candidate is scored on both signals, normalized together. Each result gets a keyword score and a vector score, brought onto the same 0–1 scale relative to the other results in this query. They are combined as score = α · vector + (1−α) · keyword.
4. α is your Semantic↔Lexical slider. Push it toward Semantic and meaning dominates (great for natural-language and conceptual queries); push it toward Lexical and exact keywords dominate (great for codes, SKUs, and proper names). See Search Tuning.

Facets, highlighting, spellcheck, sorting and pagination all keep working normally — the fused result behaves like any ordinary Solr result set.

What you get out of it

• Natural-language queries just work. Ask a question the way a human would — typos, vague phrasing, no exact keywords — and the engine maps intent to the right results.
• Cross-lingual search out of the box. Query an English catalog in Romanian, or a Romanian catalog in English — no translation dictionaries, no synonyms lists.
• Honest search modes. Intersection and Keywords-Required genuinely restrict results; Union genuinely broadens them.
• Semantic search over documents. Vector search finds relevant PDFs and other documents, not just web pages.
• No empty pages. When a shopper searches for something you don’t stock, they still see the closest relevant products instead of “0 results” — a sale instead of a bounce.

Try it — live examples

Each of these runs on a real Opensolr index. Notice how none of the queries rely on exact keywords — the meaning is what finds the result.

How to use it

There is nothing to switch on. Any vector-enabled Opensolr index (an index whose plan includes AI vector search) runs every real search through {!hybrid} automatically — on the hosted search page, through the embeddable widget, and through the API. The same engine powers the official Drupal and WordPress connectors. You shape its behaviour entirely from Search Tuning — the Semantic↔Lexical balance, the Search Mode, field weights, and the vector candidate pool.

For a technical, engineering-level description of how the parser is built and deployed across the fleet, see the Custom Solr Plugins page in the architecture manual.