Rank feature query
editRank feature query
editBoosts the relevance score of documents based on the
numeric value of a rank_feature or
rank_features field.
The rank_feature query is typically used in the should clause of a
bool query so its relevance scores are added to other
scores from the bool query.
Unlike the function_score query or other
ways to change relevance scores, the
rank_feature query efficiently skips non-competitive hits when the
track_total_hits parameter is not true. This can
dramatically improve query speed.
Rank feature functions
editTo calculate relevance scores based on rank feature fields, the rank_feature
query supports the following mathematical functions:
If you don’t know where to start, we recommend using the saturation function.
If no function is provided, the rank_feature query uses the saturation
function by default.
Example request
editIndex setup
editTo use the rank_feature query, your index must include a
rank_feature or rank_features field
mapping. To see how you can set up an index for the rank_feature query, try
the following example.
Create a test index with the following field mappings:
-
pagerank, arank_featurefield which measures the importance of a website -
url_length, arank_featurefield which contains the length of the website’s URL. For this example, a long URL correlates negatively to relevance, indicated by apositive_score_impactvalue offalse. -
topics, arank_featuresfield which contains a list of topics and a measure of how well each document is connected to this topic
PUT /test
{
"mappings": {
"properties": {
"pagerank": {
"type": "rank_feature"
},
"url_length": {
"type": "rank_feature",
"positive_score_impact": false
},
"topics": {
"type": "rank_features"
}
}
}
}
Index several documents to the test index.
PUT /test/_doc/1?refresh
{
"url": "https://en.wikipedia.org/wiki/2016_Summer_Olympics",
"content": "Rio 2016",
"pagerank": 50.3,
"url_length": 42,
"topics": {
"sports": 50,
"brazil": 30
}
}
PUT /test/_doc/2?refresh
{
"url": "https://en.wikipedia.org/wiki/2016_Brazilian_Grand_Prix",
"content": "Formula One motor race held on 13 November 2016",
"pagerank": 50.3,
"url_length": 47,
"topics": {
"sports": 35,
"formula one": 65,
"brazil": 20
}
}
PUT /test/_doc/3?refresh
{
"url": "https://en.wikipedia.org/wiki/Deadpool_(film)",
"content": "Deadpool is a 2016 American superhero film",
"pagerank": 50.3,
"url_length": 37,
"topics": {
"movies": 60,
"super hero": 65
}
}
Example query
editThe following query searches for 2016 and boosts relevance scores based on
pagerank, url_length, and the sports topic.
GET /test/_search
{
"query": {
"bool": {
"must": [
{
"match": {
"content": "2016"
}
}
],
"should": [
{
"rank_feature": {
"field": "pagerank"
}
},
{
"rank_feature": {
"field": "url_length",
"boost": 0.1
}
},
{
"rank_feature": {
"field": "topics.sports",
"boost": 0.4
}
}
]
}
}
}
Top-level parameters for rank_feature
edit-
field -
(Required, string)
rank_featureorrank_featuresfield used to boost relevance scores. -
boost -
(Optional, float) Floating point number used to decrease or increase relevance scores. Defaults to
1.0.Boost values are relative to the default value of
1.0. A boost value between0and1.0decreases the relevance score. A value greater than1.0increases the relevance score. -
saturation -
(Optional, function object) Saturation function used to boost relevance scores based on the value of the rank feature
field. If no function is provided, therank_featurequery defaults to thesaturationfunction. See Saturation for more information.Only one function
saturation,log, orsigmoidcan be provided. -
log -
(Optional, function object) Logarithmic function used to boost relevance scores based on the value of the rank feature
field. See Logarithm for more information.Only one function
saturation,log, orsigmoidcan be provided. -
sigmoid -
(Optional, function object) Sigmoid function used to boost relevance scores based on the value of the rank feature
field. See Sigmoid for more information.Only one function
saturation,log, orsigmoidcan be provided.
Notes
editSaturation
editThe saturation function gives a score equal to S / (S + pivot), where S is
the value of the rank feature field and pivot is a configurable pivot value so
that the result will be less than 0.5 if S is less than pivot and greater
than 0.5 otherwise. Scores are always (0,1).
If the rank feature has a negative score impact then the function will be
computed as pivot / (S + pivot), which decreases when S increases.
GET /test/_search
{
"query": {
"rank_feature": {
"field": "pagerank",
"saturation": {
"pivot": 8
}
}
}
}
If a pivot value is not provided, Elasticsearch computes a default value equal to the
approximate geometric mean of all rank feature values in the index. We recommend
using this default value if you haven’t had the opportunity to train a good
pivot value.
GET /test/_search
{
"query": {
"rank_feature": {
"field": "pagerank",
"saturation": {}
}
}
}
Logarithm
editThe log function gives a score equal to log(scaling_factor + S), where S
is the value of the rank feature field and scaling_factor is a configurable
scaling factor. Scores are unbounded.
This function only supports rank features that have a positive score impact.
GET /test/_search
{
"query": {
"rank_feature": {
"field": "pagerank",
"log": {
"scaling_factor": 4
}
}
}
}
Sigmoid
editThe sigmoid function is an extension of saturation which adds a configurable
exponent. Scores are computed as S^exp^ / (S^exp^ + pivot^exp^). Like for the
saturation function, pivot is the value of S that gives a score of 0.5
and scores are (0,1).
The exponent must be positive and is typically in [0.5, 1]. A
good value should be computed via training. If you don’t have the opportunity to
do so, we recommend you use the saturation function instead.
GET /test/_search
{
"query": {
"rank_feature": {
"field": "pagerank",
"sigmoid": {
"pivot": 7,
"exponent": 0.6
}
}
}
}