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.
{!hybrid} is a custom Solr query parser developed by Opensolr and deployed on our managed Solr clusters. Any vector-enabled index you host on Opensolr gets it automatically — there is nothing to set up or configure.
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
- 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.
- 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).
- 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.
- α 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. The two signals read two fields of the same document: the analysed text fields and the embeddings vector, both described in the Vector Search Schema Reference.
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 Spanish, or a German 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.
Search operators — +, - and phrases
Visitors can steer a hybrid search with the operators they already know from any search box. They work the same way with AI on and with AI off.
| Operator | What it does | Example |
|---|---|---|
"word1 word2" | Phrase — those words together, in that order | "machine learning" |
+word | Required — every result must contain it | +laptop 15 inch gaming |
+"word1 word2" | Required phrase | +"13 inch" |
-word | Excluded — drop any result containing it | laptop -refurbished |
-"word1 word2" | Excluded phrase | -"open box" |
They compose freely. The screenshot below is one query using four of them at once — a question, an excluded phrase, a required word and a required phrase — narrowing a 26,000-document news index down to the single article that answers it.
Why a prefixed term becomes a filter
This is the part worth understanding, because it is where a hybrid search differs from a plain keyword search. + and - are ordinary keyword-search syntax, so on their own they only ever reach the keyword half of the query. The meaning half has never heard of them — and in Union mode it is free to bring a document back that the keyword half just excluded.
Worse, the minus sign means nothing to an embedding model. Left inside the query text, -refurbished reads as one more word of the request, so the semantic side moves the results towards refurbished listings rather than away from them.
So Opensolr lifts a prefixed term out of the query and applies it as a filter over the whole result set. A filter binds a document no matter which half of the search found it, and the text handed to the embedding model no longer contains the term at all.
A phrase with no prefix — "machine learning" on its own — stays a keyword-side relevance signal rather than a hard filter, so a hybrid search can still surface a document that expresses the same idea in different words. Write +"machine learning" when you need the exact phrase enforced.
+ and - only count at the start of a word, so e-mail, covid-19 and 1+1 are searched for literally. A - inside a quoted phrase belongs to the phrase.
The same operators work through the hosted search page and the embeddable widget, the API, the Drupal and WordPress connectors, and all five framework packages.
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.
See the full multi-vertical gallery in the live demo guide, or read the Hybrid Search deep-dive.
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.