Search modes: keyword, semantic, hybrid

Three approaches to finding information

The retrieval_mode field accepts three values, and this choice isn’t cosmetic: it determines what the engine compares. One mode looks at words, another at meaning, and the third does both. Depending on your documents and how your users phrase their questions, the relevance gap between two modes can be dramatic on the same collection.

Keyword mode: literal matching

Keyword mode behaves like a classic search engine. It matches the words in your query against the indexed text and surfaces passages that actually contain those words.

{
  "query": "VAT rate 20%",
  "source": { "collection_ids": ["col_fiscal"] },
  "retrieval_mode": { "type": "keyword" }
}

Its strength lies in its literalness. For a product reference like “XR-2847”, an invoice number, a legal article, or an industry acronym, it doesn’t make mistakes: either the string is there, or it isn’t. It doesn’t calculate any embeddings, which makes it fast. Its weakness is the exact flip side of this quality: it understands nothing. If your document talks about “value added tax” when the user types “VAT”, the match doesn’t happen and you get zero results from a document that actually contained the answer. Everything then depends on the vocabulary coincidence between the writer and the reader, which is a risky bet as soon as your users aren’t the authors of the documents.

Semantic mode: understanding meaning

Semantic mode transforms the query and chunks into vectors, then compares meanings rather than characters. It therefore surfaces relevant passages even when no words are shared.

{
  "query": "how to reduce sales taxes",
  "source": { "collection_ids": ["col_fiscal"] },
  "retrieval_mode": { "type": "semantic" }
}

This query contains neither “VAT” nor “exemption”, and yet it will surface passages dealing with VAT, value added tax, tax deductions, or exemptions. This is exactly what you want for a public-facing assistant: your users query with their words, not with your legal department’s lexicon. The mode handles synonyms without flinching—“refund”, “credit note”, and “credit” naturally cluster together in vector space. In return, it loses precision where precision is absolute: a product code “XR-2847” looks semantically similar to “XR-2874”, and the engine might return the wrong one. Each query also requires an embedding calculation, so there’s a computational cost that doesn’t exist in keyword mode.

Hybrid mode: both signals at once

Hybrid mode is the default mode and the one xAI recommends, because it refuses the compromise. Take a typical legal query, which mixes an exact reference and a fuzzy concept.

{
  "query": "article L.121-3 director liability",
  "source": { "collection_ids": ["col_juridique"] },
  "retrieval_mode": { "type": "hybrid" }
}

Processing happens in three steps. The engine first runs a keyword search to catch exact matches, here the string “L.121-3”. It runs a semantic search in parallel that looks for passages conceptually linked to director liability, even when they don’t use those exact words. It finally merges the two lists and re-ranks them to maximize overall relevance.

The result captures both articles that explicitly cite L.121-3 and comments that deal with director liability without mentioning the article. Recall improves significantly: you miss fewer relevant documents, regardless of the question’s register. This is why hybrid works as well for a technical query as for a conversational phrase, and why it constitutes the reasonable default choice.

Two situations nevertheless justify stepping away from this setting. If you’re looking for a specific function signature in a codebase, semantic noise works against you and keyword will be sharper. Conversely, for broad exploration—“what have we written around customer loyalty?”—without a pivot term to match, semantic casts a wider net and helps you discover documents you weren’t looking for.

Mode comparison

A simple way to decide: take ten real questions from your users, run them in all three modes on the same collection, and compare the top five results. In fifteen minutes, you’ll know if your corpus leans toward exact vocabulary or toward meaning.

Key takeaways

• Keyword mode searches for exact matches—ideal for technical terms and references
• Semantic mode understands meaning—ideal for natural language questions
• Hybrid mode combines both—this is the recommended default choice
• Use keyword for searches of codes, identifiers, or exact values
• Use hybrid in all other cases