For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Hybrid search combines keyword search and vector search in the same query so results can account for both exact matches and semantic similarity.

OpenSearch supports hybrid search through a hybrid query and a search pipeline with a normalization processor. The normalization processor rescales keyword and vector scores before OpenSearch combines them into one final document score.

Use hybrid search when search quality depends on both semantic similarity and exact keyword relevance. For example, documentation search often needs to match the meaning of a question while still prioritizing exact product names, commands, error messages, configuration fields, or IDs.

For implementation steps, see Query with Hybrid Search.

Use Hybrid Search When Exact Terms Matter

Vector search is strong at semantic similarity, paraphrases, and concept matching. Keyword search is strong at exact terms, rare tokens, product names, commands, IDs, filenames, and error messages.

Use hybrid search instead of vector search alone when users search with a mix of natural language and exact terms. This helps prevent semantically similar results from outranking documents that contain important exact matches.

For mostly semantic queries, increase the vector query’s influence. For short or exact queries, increase the keyword query’s influence.

Create a Search Pipeline

Hybrid search needs a search pipeline so OpenSearch can normalize and combine scores from each sub-query.

Use a normalization-processor in the search pipeline. Start with min_max normalization and arithmetic_mean combination because they are predictable, simpler to tune, and work well for most BM25 plus k-NN workloads.

For deeper guidance on normalization and combination techniques, see Score Normalization Best Practices.

Balance Keyword and Vector Influence

Hybrid search ranking depends on how OpenSearch normalizes and combines each sub-query’s score.

Start with a balanced keyword and vector configuration because it gives you a neutral baseline before tuning for exact-match or semantic relevance.

Then, tune the balance based on query type and relevance tests:

• Favor keyword search when exact terms, product names, commands, IDs, filenames, or error messages should rank higher.
• Favor vector search when longer natural-language or semantic queries should rank higher.

Keep detailed weight values and normalization settings in the search pipeline configuration. For weight examples and normalization guidance, see Score Normalization Best Practices.

Tune Candidate Counts

The k-NN k value controls how many vector candidates OpenSearch retrieves before score normalization and combination.

Use a k value that gives OpenSearch enough vector candidates to combine with keyword results. A common starting point is at least three times the final result size. For example, if the query returns size: 10, start with k: 30.

Increase k when relevant semantic matches are missing from final results. Decrease k if latency is too high and recall is already acceptable.

Add the Right Sub-Queries

A basic hybrid query usually combines one BM25 query with one k-NN query. You can add more sub-queries when specific ranking behavior matters.

Useful sub-query patterns include:

• Add a match_phrase query when exact phrase matches should rank higher.
• Add a second knn query when documents have multiple embedding fields, such as title embeddings and body embeddings.
• Add field-specific keyword queries when some fields, such as titles or headings, should carry more weight than body text.

Keep the query simple unless relevance tests show that another sub-query improves results. More sub-queries make weights harder to tune and can increase query latency.

Use Filters for Access Control and Metadata

Use filters when hybrid search results need to respect account IDs, project IDs, permissions, timestamps, languages, sources, or object types.

Apply filters consistently across keyword and vector sub-queries so the final result set only includes documents the user should see. This is especially important for multi-tenant or permissioned search workloads.

Test filtered hybrid queries with representative tenants, projects, and permission sets. Highly selective filters can affect recall, latency, and the number of candidates available for score normalization.

Set a Default Search Pipeline

If most searches on an index use the same hybrid ranking strategy, set the search pipeline as the index’s default search pipeline.

A default search pipeline keeps client requests simpler because clients do not need to pass the search_pipeline query parameter on every request.

Use a per-request search_pipeline parameter instead when you need different ranking strategies for different query types, applications, or experiments.

Test Relevance with Representative Queries

Tune hybrid search with a test set of representative queries and known relevant documents.

Include different query types in the test set:

• Natural-language questions.
• Short keyword queries.
• Product names.
• Commands.
• Error messages.
• IDs or filenames.
• Queries with metadata filters.

Use the same test set when comparing weights, normalization techniques, candidate counts, and sub-query combinations. This helps you tell whether a change improves relevance or only changes the result order.

Debug Hybrid Scores

Use score explanations when results do not rank as expected.

OpenSearch can show how each sub-query contributes to a hit’s final hybrid score when you use a debug search pipeline with score explanations. Use this when you need to understand whether BM25, k-NN, normalization, or weights are driving the final ranking.

When debugging relevance, check:

• Whether each sub-query returns the expected candidates.
• Whether the weights match the sub-query order.
• Whether k is large enough for the vector query.
• Whether filters remove expected results.
• Whether exact matches need stronger keyword or phrase-query weighting.
• Whether semantic matches need stronger vector weighting.

After debugging, make one tuning change at a time and compare results against the same test set.