QueryMatchRatio computes a normalized [0, 1] score representing how many terms in a search query matched in an index. Specifically, the score is the ratio of terms that a search query hits in a specific field or all fields of an index to all terms in the index. A score of 0 means no terms matched; a score of 1 means every term matched. Use this score as a component in custom relevance formulas to reward documents that cover more of the query.
In OpenSearch, an index can contain multiple fields. If a term in a search query hits a term in one of the fields of an index, the corresponding document is returned in results.
OpenSearch supports two calculation scopes:
All-fields mode — counts matched query terms across every field in the index.
Single-field mode — counts matched query terms in one specific field of the index.
Example: A default index has two fields: title and body. For the query default:'User Manual', all-fields mode returns the match ratio across both fields combined. Single-field mode returns the ratio for title only or body only.
Use all-fields mode when you want to reward documents where query terms appear anywhere in the index. Use single-field mode when field-level precision matters — for example, boosting documents where query terms appear in the title field specifically.
Functions
| Signature | Description |
|---|---|
QueryMatchRatio create(OpsScorerInitParams params) | Creates an instance scoped to all fields of the default index. |
QueryMatchRatio create(OpsScorerInitParams params, CString indexName) | Creates an instance scoped to all fields of a specific index. |
QueryMatchRatio create(OpsScorerInitParams params, CString indexName, CString fieldName) | Creates an instance scoped to one field of a specific index. |
void setGroupScoreMergeOp(CString opName) | Sets how scores from multiple query groups are combined. Supported values: sum (default), max. |
double evaluate(OpsScoreParams params) | Returns the query match ratio. Valid range: [0, 1]. |
Function details
create(OpsScorerInitParams params)
Creates a QueryMatchRatio instance scoped to all fields of the default index.
Parameters:
| Parameter | Type | Description |
|---|---|---|
params | OpsScorerInitParams | Initialization parameters. See OpsScorerInitParams. |
create(OpsScorerInitParams params, CString indexName)
Creates a QueryMatchRatio instance scoped to all fields of a specific index.
Parameters:
| Parameter | Type | Description |
|---|---|---|
params | OpsScorerInitParams | Initialization parameters. See OpsScorerInitParams. |
indexName | CString | The name of the index. Must be a constant. Supported analyzers: general analyzer for Chinese, custom analyzer, single character analyzer for Chinese, analyzer for English, and analyzer for fuzzy searches. |
create(OpsScorerInitParams params, CString indexName, CString fieldName)
Creates a QueryMatchRatio instance scoped to one field of a specific index.
Parameters:
| Parameter | Type | Description |
|---|---|---|
params | OpsScorerInitParams | Initialization parameters. See OpsScorerInitParams. |
indexName | CString | The name of the index. Must be a constant. Supported analyzers: general analyzer for Chinese, custom analyzer, single character analyzer for Chinese, analyzer for English, and analyzer for fuzzy searches. |
fieldName | CString | The name of a field in the index specified by indexName. Must be a constant. |
setGroupScoreMergeOp(CString opName)
Sets the aggregation method for QueryMatchRatio scores across multiple query groups.
Call this method only during scorer initialization. Query groups are generated when the analyzer processes the original search query. By default, only one query group exists.
Parameters:
| Parameter | Type | Description |
|---|---|---|
opName | CString | The aggregation method for scores across multiple query groups. Valid values: sum (default) and max. Use sum to accumulate scores from all query groups. Use max to let the best-matching group dominate. |
evaluate(OpsScoreParams params)
Returns the query match ratio for the configured index scope. The ratio is the number of terms that the search query hits in the specified field or all fields of the index to all terms in the index.
Parameters:
| Parameter | Type | Description |
|---|---|---|
params | OpsScoreParams | Score calculation parameters. See OpsScoreParams. |
Return value: A double in [0, 1]. A value of 0 means no query terms matched; a value of 1 means all query terms matched.
Example
The following example creates two QueryMatchRatio instances and combines their scores. The scorer adds the index-scoped ratio (title_index only) to the all-fields ratio of the default index, so documents where query terms appear in the title index and across all fields rank higher.
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.similarity.querymatch.QueryMatchRatio;
class BasicSimilarityScorer {
QueryMatchRatio _f1; // All-fields mode: scoped to all fields of title_index
QueryMatchRatio _f2; // All-fields mode: scoped to all fields of the default index
boolean init(OpsScorerInitParams params) {
_f1 = QueryMatchRatio.create(params, "title_index"); // Boost title_index matches
_f2 = QueryMatchRatio.create(params); // Reward any-field matches
return true;
}
double score(OpsScoreParams params) {
return _f1.evaluate(params) + _f2.evaluate(params); // Combine both signals
}
}