KeyWordsMatched-OpenSearch(Open Search)-阿里云帮助中心

KeyWordsMatched measures keyword coverage in a specified field and returns a score that reflects how well a search query's keywords match that field. Use it as a scoring factor when you need to quantify keyword coverage and influence relevance ranking based on that coverage.

Functions

Function	Description
`KeyWordsMatched create(OpsScorerInitParams params, CString indexName, CString fieldName)`	Creates a `KeyWordsMatched` object. This is a factory function.
`void setGroupScoreMergeOp(CString opName)`	Sets the aggregation method for `KeyWordsMatched` scores across multiple query groups.
`double evaluate(OpsScoreParams params)`	Returns the keyword match score for a specific field.

Function details

`KeyWordsMatched create(OpsScorerInitParams params, CString indexName, CString fieldName)`

Creates a KeyWordsMatched object. Call this function during scorer initialization to bind the instance to a specific index and field.

Parameters

Parameter	Type	Required	Description
`params`	`OpsScorerInitParams`	Yes	Initialization parameters. See OpsScorerInitParams.
`indexName`	`CString`	Yes	The name of the index. Must be a constant.
`fieldName`	`CString`	Yes	The name of the field in the specified index. Must be a constant. The field must be of type `TEXT` or `SHORT_TEXT`.

Supported analyzers for `fieldName`

General analyzer for Chinese
Custom analyzer
Single character analyzer for Chinese
Analyzer for English
Analyzer for fuzzy searches

Note

The analyzer configured for the field determines how keywords are derived at score calculation time. When an analyzer is used, keywords come from the analyzer's output. Otherwise, keywords are derived from the term combination logic in the search query.

`void setGroupScoreMergeOp(CString opName)`

Sets the aggregation method for KeyWordsMatched scores across multiple query groups.

Call this function only during scorer initialization. Query groups are produced when an analyzer processes the original search query. By default, only one query group exists.

Parameter

Parameter	Type	Required	Description
`opName`	`CString`	Yes	The aggregation method for scores across query groups. Valid values: `sum` (default), `max`.

When to use `max` instead of `sum`

Use sum (default) when you want the total keyword coverage across all query groups to influence the score.
Use max when you want only the best-matching query group to determine the score, preventing lower-quality groups from reducing it.

`double evaluate(OpsScoreParams params)`

Returns the keyword match score for the field bound during initialization.

Parameter

Parameter	Type	Required	Description
`params`	`OpsScoreParams`	Yes	Score calculation parameters. See OpsScoreParams.

Return values

Value	Meaning
`0`	No query terms appear in the field.
`0.5`	The search query's keywords appear in the field, but not all analyzed terms do.
`1.0`	All analyzed terms from the search query appear in the field.

Example: For the query A AND B RANK C:

If none of A, B, or C appear in the field, returns 0.
If only A and B appear, returns 0.5.
If A, B, and C all appear, returns 1.0.

Code example

The following example creates a KeyWordsMatched instance bound to text_field in pack_index1, then uses evaluate() to return its score as the document's relevance score.

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.KeyWordsMatched;

class BasicSimilarityScorer {
    KeyWordsMatched _f1;

    boolean init(OpsScorerInitParams params) {
        // Bind KeyWordsMatched to the "text_field" field in "pack_index1"
        _f1 = KeyWordsMatched.create(params, "pack_index1", "text_field");
        return true;
    }

    double score(OpsScoreParams params) {
        // Returns 0, 0.5, or 1.0 based on keyword coverage in text_field
        return _f1.evaluate(params);
    }
}