FieldTermProximity - OpenSearch - Alibaba Cloud Documentation Center

FieldTermProximity scores documents based on how closely together query terms appear within a specific field. The score reflects the relevance of the term to the field and also indicates whether the term appears contiguously (integral) within the field.

For example, given the query term "User Manual":

Field 1: OpenSearch User Manual — terms appear contiguous, higher proximity score
Field 2: Users use OpenSearch Manual to solve problems — terms are separated by intervening tokens, lower proximity score

Use this class in a custom CAVA scorer to boost documents where query terms cluster together in a specific text field.

Functions

Signature	Description
`FieldTermProximity create(OpsScorerInitParams params, CString indexName, CString fieldName)`	Creates a `FieldTermProximity` object for the specified index and field.
`void setGroupScoreMergeOp(CString opName)`	Sets how proximity scores from multiple query groups are merged. Supported operators: `sum` (default) and `max`.
`double evaluate(OpsScoreParams params)`	Returns the proximity score for the query term in the specified field.

Function details

create()

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

Parameter	Type	Description
`params`	`OpsScorerInitParams`	Parameters for score calculation. See OpsScoreParams.
`indexName`	`CString`	Name of the index. Must be a constant, not a variable.
`fieldName`	`CString`	Name of a field in the specified index. Must be a constant, not a variable.

Field type requirement: The field must be of type TEXT or SHORT_TEXT.

Supported analyzers:

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

setGroupScoreMergeOp()

Sets how proximity scores from multiple query groups are combined into a single score.

Important

Call this method inside the init function, not the score function.

Parameter	Type	Description
`opName`	`CString`	Merge operator. Valid values: `sum` or `max`. Default: `sum`.

Operator	Behavior
`sum`	Adds the proximity scores from all query groups.
`max`	Returns the highest proximity score across all query groups.

evaluate()

Calculates and returns the proximity score for the query term in the field bound to this object.

Parameter	Type	Description
`params`	`OpsScoreParams`	Parameters for score calculation. See OpsScoreParams.

Return value: A double in the range [0, 1]. Higher values indicate closer term proximity.

Example

The following example creates a scorer that uses FieldTermProximity on the text field of text_index. The max operator is used so that the highest proximity score across query groups drives the final score.

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.distribution.FieldTermProximity;

class BasicSimilarityScorer {
    FieldTermProximity _proximity;
    boolean init(OpsScorerInitParams params) {
        _proximity = FieldTermProximity.create(params, "text_index","text");
        _proximity.setGroupScoreMergeOp("max");
        return true;
    }

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