When search results don't match expectations, the issue typically stems from one of three factors: how the query is analyzed into terms, how those terms match documents, and how matched documents are scored and ranked. This topic explains each factor and how to tune OpenSearch to return the results your users expect.
Analysis method
Query analysis is the first step in every search. OpenSearch tokenizes the search query into individual terms before matching begins. For details on available analyzers and how to configure them, see Built-in analyzers.
Matching method
How it works
After analysis, OpenSearch uses the resulting terms to retrieve documents. By default, only documents that contain all terms are returned — the default operator is AND.
OpenSearch supports five logical operators for building query clauses:
| Logical operator | Syntax | Result |
|---|---|---|
| (default AND) | query=title:"Apple Mobile phone" | Returns documents where the title contains both Apple and Mobile phone. |
| AND | query=title:'Apple' AND cate:'Mobile phone' | Returns the intersection: title contains Apple and cate contains Mobile phone. |
| OR | query=title:'Apple' OR cate:'Mobile phone' | Returns the union: title contains Apple or cate contains Mobile phone. |
| RANK | query=title:'Apple' RANK cate:'Mobile phone' | Returns documents where title contains Apple; documents where cate also contains Mobile phone receive a higher score. |
| ANDNOT | query=title:'Apple' ANDNOT cate:'Mobile phone' | Returns documents where title contains Apple and cate does not contain Mobile phone. |
Operator priority in descending order: () > ANDNOT > AND > OR > RANK.
For the full query syntax, see Query clause.
FAQ
My document contains "Eat the Meal" and is returned when I search "Eat" or "Eat the Meal". Why isn't it returned when I search "You Eat the Meal"?
OpenSearch returns only documents that contain all analyzed terms. The term "You" doesn't appear in your document, so the document doesn't match. To handle this, configure query analysis to adjust how the query is tokenized before matching.
Can I search for documents that start with a specific term, such as "KFC"?
No. OpenSearch does not support retrieval based on term position within a document.
Relevance-based score calculation
How it works
OpenSearch uses a two-phase scoring pipeline to balance speed and accuracy:
Rough sort — Scores all candidate documents using a fast expression. The number of documents scored in this phase equals the value of the
rank_sizeparameter, which is one million. The goal is to quickly surface high-quality candidates for the next phase.Fine sort — Re-scores the top N documents from rough sort using a more detailed expression. Hundreds of documents are involved. Final results are returned based on the
startandhitparameters. If the requested number of results exceeds N, the remaining results beyond N fall back to their rough sort scores.
Default sort behavior
If no sort clause is specified, OpenSearch defaults to sort=-RANK, sorting results by relevance score in descending order. To sort by multiple dimensions, chain clauses — for example, sort=-RANK;+bonus ranks by relevance first, then by bonus in ascending order when scores are equal.
RANK can be applied in a rough sort expression or a fine sort expression.
Rough sort expressions
Rough sort affects both latency and result quality — only documents that pass this phase reach fine sort. Keep rough sort expressions simple and fast. Supported building blocks:
Forward indexes (simple field values)
static_bm25()— text relevance score based on BM25timeliness()— recency score based on a timestamp field
Fine sort expressions
Fine sort expressions support mathematical and logical operations and have access to a full library of built-in functions. Use fine sort to capture nuanced signals like text relevance across multiple fields, distance, engagement metrics, and business rules.
Sort expression examples
OpenSearch provides built-in schemas and expressions for common scenarios. The following examples show how rough and fine sort expressions work together:
| Scenario | Expression | Signals |
|---|---|---|
| Forum: Rough sort | static_bm25() | Text relevance |
| Forum: Fine sort | text_relevance(title)*3+text_relevance(body)+if(text_relevance(title)>0.07,timeliness(create_timestamp),timeliness(create_timestamp)*0.5)+(topped+special+atan(hits)*0.5+atan(replies))*0.1 | Text relevance, recency, engagement (pins, replies, views) |
| O2O (online to offline): Rough sort | sold_score+general_score*2 | Sales volume, overall store score (pre-computed offline) |
| O2O: Fine sort | 2*sold_score+0.5*reward- 10*distance(lon,lat,u_posx,u_posy)+ if ((flags&2) =2, 2, 0)+if(is_open=5,10,0)+ special_score | Sales volume, delivery speed, punctuality, distance, availability, operational status |
| Fiction: Rough sort | static_bm25()*0.7+hh_hot*0.00003 | Text relevance, popularity |
| Fiction: Fine sort | pow(min(0.5,max(text_relevance(category),max(text_relevance(title), text_relevance(author)))),2)+ general_score*2+ 1.5*(1/(1+pow(2.718281,-((log10(hh_hot)-2)*2-5))))) | Category, title, author relevance; content quality; popularity |
| E-commerce: Rough sort | static_bm25()+general_score*2+timeliness(end_time) | Text relevance, overall product score, listing expiration |
| E-commerce: Fine sort | text_relevance(title)*3+text_relevance(category)+ general_score*2+boughtScore*2+ tag_match(ctr_query_value,doc_value,mul,sum,false,true)+.. | Title and category relevance, popularity, seller ratings, click-through rate (CTR) estimation, feature rules |
FAQ
Why does `text_relevance(seller_id)` fail to find the field?
text_relevance() works only with fields of type TEXT or SHORT_TEXT. If seller_id is a different type, the function cannot process it.
Why is error 2112 reported?
Error 2112 occurs when the fields in the sort expression don't match the fields in the query clause. For example, if the query clause is query=default:'keyword' (which resolves to the title and body fields) but the expression is text_relevance(title)+text_relevance(author), the author field is not in the query clause and triggers the error. Make sure every field referenced in the fine sort expression also appears in the query clause.
Tips
Pre-compute static scores offline. Signals that don't change per query — such as seller ratings, popularity, or content quality — are expensive to compute at query time. Store them in a general_score field calculated offline, then reference general_score in your sort expression. This reduces computation during search and improves latency.
Use `tag_match()` for multi-dimensional feature matching. The tag_match() function compares feature vectors between the query and documents across multiple dimensions. It is particularly effective for e-commerce ranking where signals like user preferences, product attributes, and historical click patterns need to be combined.
Treat relevance as a weighted combination of signals. No single signal captures all aspects of quality. Adjust the weight of each factor — text match, recency, popularity, business rules — to match the ranking behavior your users expect.