[[query-dsl-rank-feature-query]]
=== Rank feature query
++++
<titleabbrev>Rank feature</titleabbrev>
++++
Boosts the <<relevance-scores,relevance score>> of documents based on the
numeric value of a <<rank-feature,`rank_feature`>> or
<<rank-features,`rank_features`>> field.
The `rank_feature` query is typically used in the `should` clause of a
<<query-dsl-bool-query,`bool`>> query so its relevance scores are added to other
scores from the `bool` query.
Unlike the <<query-dsl-function-score-query,`function_score`>> query or other
ways to change <<relevance-scores,relevance scores>>, the
`rank_feature` query efficiently skips non-competitive hits when the
<<search-uri-request,`track_total_hits`>> parameter is **not** `true`. This can
dramatically improve query speed.
[[rank-feature-query-functions]]
==== Rank feature functions
To calculate relevance scores based on rank feature fields, the `rank_feature`
query supports the following mathematical functions:
* <<rank-feature-query-saturation,Saturation>>
* <<rank-feature-query-logarithm,Logarithm>>
* <<rank-feature-query-sigmoid,Sigmoid>>
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.
[[rank-feature-query-ex-request]]
==== Example request
[[rank-feature-query-index-setup]]
===== Index setup
To use the `rank_feature` query, your index must include a
<<rank-feature,`rank_feature`>> or <<rank-features,`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`, a <<rank-feature,`rank_feature`>> field which measures the
importance of a website
- `url_length`, a <<rank-feature,`rank_feature`>> field which contains the
length of the website's URL. For this example, a long URL correlates negatively
to relevance, indicated by a `positive_score_impact` value of `false`.
- `topics`, a <<rank-features,`rank_features`>> field which contains a list of
topics and a measure of how well each document is connected to this topic
[source,console]
----
PUT /test
{
"mappings": {
"properties": {
"pagerank": {
"type": "rank_feature"
},
"url_length": {
"type": "rank_feature",
"positive_score_impact": false
},
"topics": {
"type": "rank_features"
}
}
}
}
----
// TESTSETUP
Index several documents to the `test` index.
[source,console]
----
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
}
}
----
[[rank-feature-query-ex-query]]
===== Example query
The following query searches for `2016` and boosts relevance scores based on
`pagerank`, `url_length`, and the `sports` topic.
[source,console]
----
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
}
}
]
}
}
}
----
[[rank-feature-top-level-params]]
==== Top-level parameters for `rank_feature`
`field`::
(Required, string) <<rank-feature,`rank_feature`>> or
<<rank-features,`rank_features`>> field used to boost
<<relevance-scores,relevance scores>>.
`boost`::
+
--
(Optional, float) Floating point number used to decrease or increase
<<relevance-scores,relevance scores>>. Defaults to `1.0`.
Boost values are relative to the default value of `1.0`. A boost value between
`0` and `1.0` decreases the relevance score. A value greater than `1.0`
increases the relevance score.
--
`saturation`::
+
--
(Optional, <<rank-feature-query-saturation,function object>>) Saturation
function used to boost <<relevance-scores,relevance scores>> based on the
value of the rank feature `field`. If no function is provided, the `rank_feature`
query defaults to the `saturation` function. See
<<rank-feature-query-saturation,Saturation>> for more information.
Only one function `saturation`, `log`, or `sigmoid` can be provided.
--
`log`::
+
--
(Optional, <<rank-feature-query-logarithm,function object>>) Logarithmic
function used to boost <<relevance-scores,relevance scores>> based on the
value of the rank feature `field`. See
<<rank-feature-query-logarithm,Logarithm>> for more information.
Only one function `saturation`, `log`, or `sigmoid` can be provided.
--
`sigmoid`::
+
--
(Optional, <<rank-feature-query-sigmoid,function object>>) Sigmoid function used
to boost <<relevance-scores,relevance scores>> based on the value of the
rank feature `field`. See <<rank-feature-query-sigmoid,Sigmoid>> for more
information.
Only one function `saturation`, `log`, or `sigmoid` can be provided.
--
[[rank-feature-query-notes]]
==== Notes
[[rank-feature-query-saturation]]
===== Saturation
The `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.
[source,console]
--------------------------------------------------
GET /test/_search
{
"query": {
"rank_feature": {
"field": "pagerank",
"saturation": {
"pivot": 8
}
}
}
}
--------------------------------------------------
If a `pivot` value is not provided, {es} 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.
[source,console]
--------------------------------------------------
GET /test/_search
{
"query": {
"rank_feature": {
"field": "pagerank",
"saturation": {}
}
}
}
--------------------------------------------------
[[rank-feature-query-logarithm]]
===== Logarithm
The `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.
[source,console]
--------------------------------------------------
GET /test/_search
{
"query": {
"rank_feature": {
"field": "pagerank",
"log": {
"scaling_factor": 4
}
}
}
}
--------------------------------------------------
[[rank-feature-query-sigmoid]]
===== Sigmoid
The `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.
[source,console]
--------------------------------------------------
GET /test/_search
{
"query": {
"rank_feature": {
"field": "pagerank",
"sigmoid": {
"pivot": 7,
"exponent": 0.6
}
}
}
}
--------------------------------------------------