FieldMatchRatio scores a search query by calculating the ratio of matched terms to total terms in a specific field. Use it to quantify how closely a query covers the content of a field.
Formula: score = matched terms / total terms in field
Example: The title field contains five terms after analysis: field, match, ratio, user, guide. A query that analyzes to OpenSearch, user, guide matches two of those terms. The FieldMatchRatio score is 2 / 5 = 0.4.
Methods
| Method | Description |
|---|---|
FieldMatchRatio create(OpsScorerInitParams params, CString indexName, CString fieldName) | Creates a FieldMatchRatio object for a specific index and field. |
void setGroupScoreMergeOp(CString opName) | Sets how scores from multiple query groups are aggregated. |
double evaluate(OpsScoreParams params) | Returns the FieldMatchRatio score for the query in the specified field. |
Method details
FieldMatchRatio create(OpsScorerInitParams params, CString indexName, CString fieldName)
A factory function that creates a FieldMatchRatio object bound to a specific index and field.
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 the field in the specified index. Must be a constant. The field must be of the TEXT or SHORT_TEXT type. |
void setGroupScoreMergeOp(CString opName)
Sets the aggregation method applied when a search query spans multiple query groups.
Call this method inside the init function.
Parameter `opName`:
| Operator | Behavior | When to use |
|---|---|---|
sum (default) | Adds the FieldMatchRatio scores of all query groups. | Use when all query groups contribute to relevance and you want to reward broader coverage. |
max | Returns the highest FieldMatchRatio score among all query groups. | Use when only the best-matching group should determine the score, for example in disjunctive queries. |
double evaluate(OpsScoreParams params)
Calculates the FieldMatchRatio score for the current query in the field specified during create.
Parameter:
| Parameter | Type | Description |
|---|---|---|
params | OpsScoreParams | Parameters for score calculation. See OpsScoreParams. |
Return value: A score in the range [0, 1], where 1 means every term in the field was matched.
Example:
package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.features.similarity.fieldmatch.FieldMatchRatio;
class BasicSimilarityScorer {
FieldMatchRatio _fieldMathcRatio;
boolean init(OpsScorerInitParams params) {
_fieldMatchRatio = FieldMatchRatio.create(params, "title_index", "title");
_fieldMatchRatio.setGroupScoreMergeOp("max");
return true;
}
double score(OpsScoreParams params) {
return _fieldMathcRatio.evaluate(params);
}
}In this example, FieldMatchRatio is bound to the title field in title_index. The max operator is set during init, so only the highest-scoring query group determines the final score. Calling evaluate in the score function returns a value between 0 and 1.