TextRelevance computes a relevance score between a search query and a specified field in a specified index. Scores range from 0 to 1, where higher values indicate greater relevance.
How it works
TextRelevance combines three scoring components:
| Component | What it measures |
|---|---|
| FieldMatchWeighted | Proportion of hit terms in the query and in the field |
| BM25 | Frequency of hit terms in the field |
| FieldTermProximity | Order of hit terms in the field relative to query order |
Use the weight-setter functions to adjust how much each component contributes to the final score.
Functions
| Function | Description |
|---|---|
TextRelevance create(OpsScorerInitParams params, CString indexName, CString fieldName) | Creates a TextRelevance object for the specified index and field. |
void setGroupScoreMergeOp(CString opName) | Sets the aggregation method (sum or max) for scores across multiple query groups. Default: sum. |
void setFieldBm25Weight(double weight) | Sets the weight of BM25 scores. Default: 0.5. |
void setFieldMatchWeightedWeight(double weight) | Sets the weight of FieldMatchWeighted scores. Default: 5. |
void setFieldTermProximityWeight(double weight) | Sets the weight of FieldTermProximity scores. Default: 9. |
double evaluate(OpsScoreParams params) | Calculates the text relevance score. Returns a value in [0, 1]. |
Function details
create
TextRelevance create(OpsScorerInitParams params, CString indexName, CString fieldName)Creates a TextRelevance object to calculate the relevance between a search query and the specified field.
Parameters
| Parameter | Type | Description |
|---|---|---|
params | OpsScorerInitParams | The initialization parameters for score calculation. For more information, see OpsScorerInitParams. |
indexName | CString | The name of the index. Must be a constant. |
fieldName | CString | The name of the field in the index. Must be a constant. 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, and analyzer for fuzzy searches. |
setGroupScoreMergeOp
void setGroupScoreMergeOp(CString opName)Sets the aggregation method for text relevance scores across multiple query groups.
An analyzer may split a search query into multiple query groups. By default, only one query group exists. Call this function only during scorer initialization.
Parameters
| Parameter | Type | Description |
|---|---|---|
opName | CString | The aggregation method. Valid values: sum (default), max. |
setFieldBm25Weight
void setFieldBm25Weight(double weight)Sets the weight of BM25 scores. Call this function only during scorer initialization. Default: 0.5.
Parameters
| Parameter | Type | Description |
|---|---|---|
weight | double | The weight of BM25 scores. |
setFieldMatchWeightedWeight
void setFieldMatchWeightedWeight(double weight)Sets the weight of FieldMatchWeighted scores. Call this function only during scorer initialization. Default: 5.
Parameters
| Parameter | Type | Description |
|---|---|---|
weight | double | The weight of FieldMatchWeighted scores. |
setFieldTermProximityWeight
void setFieldTermProximityWeight(double weight)Sets the weight of FieldTermProximity scores. Call this function only during scorer initialization. Default: 9.
Parameters
| Parameter | Type | Description |
|---|---|---|
weight | double | The weight of FieldTermProximity scores. |
evaluate
double evaluate(OpsScoreParams params)Calculates the text relevance between the search query and the specified field.
Parameters
| Parameter | Type | Description |
|---|---|---|
params | OpsScoreParams | The parameters for score calculation. For more information, see OpsScoreParams. |
Return value
The text relevance score. Valid values: [0, 1]. A higher value indicates greater relevance.
Example
The following example creates a TextRelevance scorer, overrides the default component weights, and uses it to score documents.
All weight-setter calls use the init() method, which is the correct place to configure a scorer.
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.TextRelevance;
class BasicSimilarityScorer {
TextRelevance _f1;
boolean init(OpsScorerInitParams params) {
_f1 = TextRelevance.create(params, "text_index", "text");
_f1.setGroupScoreMergeOp("max");
_f1.setFieldBm25Weight(2);
_f1.setFieldMatchWeightedWeight(3);
_f1.setFieldTermProximityWeight(4);
return true;
}
double score(OpsScoreParams params) {
return _f1.evaluate(params);
}
}