FieldMatchWeighted - OpenSearch - Alibaba Cloud Documentation Center

FieldMatchWeighted scores how well a search query matches a specific field in an index. The more query terms hit in the field, the higher the score. Use this class to build custom relevance scorers in OpenSearch Industry Algorithm Edition.

How it works

Each FieldMatchWeighted score combines two components:

baseScore — a term-frequency weighted score. The weight of each term (tw) is generated by query analysis; the default tw is 1.
bonusScore — an additional weighted score applied when the query exactly matches the field value, or when the query is a substring of the field value.

The final score is calculated as:

score = (A × baseScore + bonusScore) / (A + 1)

where A is the weight of baseScore relative to bonusScore. The following figure illustrates how baseScore is calculated.

Bonus score conditions

bonusScore applies in two distinct situations:

Condition	Triggered when	Controlled by
Exact match	The query equals the entire field value	`setExactMatchBonus()`
Substring match (ngram)	The query appears within the field value	`setNgramMatchBonus()`

Example:

Field value: "Apple iPhone 15 Pro"
Query "Apple iPhone 15 Pro" → exact match; exactMatchBonus applies.
Query "iPhone 15 Pro" → query is contained in the field; ngramMatchBonus applies.

Functions

Note: All setter functions (setGroupScoreMergeOp, setParamA, setExactMatchBonus, setNgramMatchBonus) must be called inside init(), not inside score(). Calling them after initialization has no effect.

Function	Description
`FieldMatchWeighted create(OpsScorerInitParams params, CString indexName, CString fieldName)`	Creates a `FieldMatchWeighted` object.
`void setGroupScoreMergeOp(CString opName)`	Sets how scores from multiple query groups are aggregated. Supported values: `sum`, `max`. Default: `sum`.
`void setParamA(double paramA)`	Sets variable `A` — the weight of `baseScore` in the final formula. Default: `0.5`.
`void setExactMatchBonus(double exactMatchBonus)`	Sets the bonus score when the query exactly matches the field. Default: `1.0`.
`void setNgramMatchBonus(double ngramMatchBonus)`	Sets the bonus score when the query is contained within the field. Default: `0.6`.
`double evaluate(OpsScoreParams params)`	Returns the relevance score between the query and the field. Valid range: `[0, 1]`.

Function details

create()

FieldMatchWeighted create(OpsScorerInitParams params, CString indexName, CString fieldName)

Creates a FieldMatchWeighted object bound to a specific index and field.

Parameter	Type	Description
`params`	`OpsScorerInitParams`	Initialization parameters. See OpsScorerInitParams.
`indexName`	`CString`	Name of the index. Must be a constant.
`fieldName`	`CString`	Name of the field within the index. Must be a constant. Must be of type `TEXT` or `SHORT_TEXT`.

Supported analyzers for the target field: general Chinese analyzer, custom analyzer, single-character Chinese analyzer, English analyzer, and fuzzy search analyzer.

setGroupScoreMergeOp()

void setGroupScoreMergeOp(CString opName)

Sets how FieldMatchWeighted scores are aggregated across multiple query groups. Query groups are produced when the analyzer splits the original search query into separate segments. By default, a single query group exists.

Parameter	Supported values	Default
`opName`	`"sum"`, `"max"`	`"sum"`

setParamA()

void setParamA(double paramA)

Sets variable A in the scoring formula (A × baseScore + bonusScore) / (A + 1). A higher value gives more weight to baseScore relative to bonusScore.

Parameter	Default
`paramA`	`0.5`

setExactMatchBonus()

void setExactMatchBonus(double exactMatchBonus)

Sets the bonus score added when the query exactly matches the full field value.

Parameter	Default
`exactMatchBonus`	`1.0`

setNgramMatchBonus()

void setNgramMatchBonus(double ngramMatchBonus)

Sets the bonus score added when the query is contained within the field value (substring match).

Parameter	Default
`ngramMatchBonus`	`0.6`

evaluate()

double evaluate(OpsScoreParams params)

Calculates the relevance of the search query against the configured field.

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

Returns a double in the range [0, 1].

Example

The following example creates a FieldMatchWeighted scorer for the title field in the title_index index. All setter calls go inside init(); score() calls only evaluate().

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

class BasicSimilarityScorer {
    FieldMatchWeighted _f1;

    boolean init(OpsScorerInitParams params) {
        // Required: bind to a specific index and field
        _f1 = FieldMatchWeighted.create(params, "title_index", "title");

        // Optional: use the highest score across query groups instead of summing them
        _f1.setGroupScoreMergeOp("max"); // default: "sum"

        // Optional: give baseScore full weight (A=1) relative to bonusScore
        _f1.setParamA(1);               // default: 0.5

        // Optional: tune bonus scores for match conditions
        _f1.setExactMatchBonus(0.5);    // default: 1.0
        _f1.setNgramMatchBonus(0.3);    // default: 0.6

        return true;
    }

    double score(OpsScoreParams params) {
        return _f1.evaluate(params);
    }
}