OpenSearch/docs/reference/query-dsl/feature-query.asciidoc

[[query-dsl-feature-query]]
=== Feature Query

The `feature` query is a specialized query that only works on
<<feature,`feature`>> fields and <<feature-vector,`feature_vector`>> fields.
Its goal is to boost the score of documents based on the values of numeric
features. It is typically put in a `should` clause of a
<<query-dsl-bool-query,`bool`>> query so that its score is added to the score
of the query.

Compared to using <<query-dsl-function-score-query,`function_score`>> or other
ways to modify the score, this query has the benefit of being able to
efficiently skip non-competitive hits when
<<search-uri-request,`track_total_hits`>> is set to `false`. Speedups may be
spectacular.

Here is an example that indexes various features:
 - https://en.wikipedia.org/wiki/PageRank[`pagerank`], a measure of the
   importance of a website,
 - `url_length`, the length of the url, which typically correlates negatively
   with relevance,
 - `topics`, which associates a list of topics with every document alongside a
   measure of how well the document is connected to this topic.

Then the example includes an example query that searches for `"2016"` and boosts
based or `pagerank`, `url_length` and the `sports` topic.

[source,js]
--------------------------------------------------
PUT test
{
  "mappings": {
    "_doc": {
      "properties": {
        "pagerank": {
          "type": "feature"
        },
        "url_length": {
          "type": "feature",
          "positive_score_impact": false
        },
        "topics": {
          "type": "feature_vector"
        }
      }
    }
  }
}

PUT test/_doc/1
{
  "url": "http://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
{
  "url": "http://en.wikipedia.org/wiki/2016_Brazilian_Grand_Prix",
  "content": "Formula One motor race held on 13 November 2016 at the Autódromo José Carlos Pace in São Paulo, Brazil",
  "pagerank": 50.3,
  "url_length": 47,
  "topics": {
    "sports": 35,
    "formula one": 65,
    "brazil": 20
  }
}

PUT test/_doc/3
{
  "url": "http://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
  }
}

POST test/_refresh

GET test/_search 
{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "content": "2016"
          }
        }
      ],
      "should": [
        {
          "feature": {
            "field": "pagerank"
          }
        },
        {
          "feature": {
            "field": "url_length",
            "boost": 0.1
          }
        },
        {
          "feature": {
            "field": "topics.sports",
            "boost": 0.4
          }
        }
      ]
    }
  }
}
--------------------------------------------------
// CONSOLE

[float]
=== Supported functions

The `feature` query supports 3 functions in order to boost scores using the
values of features. If you do not know where to start, we recommend that you
start with the `saturation` function, which is the default when no function is
provided.

[float]
==== Saturation

This function gives a score that is equal to `S / (S + pivot)` where `S` is the
value of the feature 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 is +(0, 1)+.

If the feature has a negative score impact then the function will be computed as
`pivot / (S + pivot)`, which decreases when `S` increases.

[source,js]
--------------------------------------------------
GET test/_search
{
  "query": {
    "feature": {
      "field": "pagerank",
      "saturation": {
        "pivot": 8
      }
    }
  }
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

If +pivot+ is not supplied then Elasticsearch will compute a default value that
will be approximately equal to the geometric mean of all feature values that
exist in the index. We recommend this if you haven't had the opportunity to
train a good pivot value.

[source,js]
--------------------------------------------------
GET test/_search
{
  "query": {
    "feature": {
      "field": "pagerank",
      "saturation": {}
    }
  }
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

[float]
==== Logarithm

This function gives a score that is equal to `log(scaling_factor + S)` where
`S` is the value of the feature and `scaling_factor` is a configurable scaling
factor. Scores are unbounded.

This function only supports features that have a positive score impact.

[source,js]
--------------------------------------------------
GET test/_search
{
  "query": {
    "feature": {
      "field": "pagerank",
      "log": {
        "scaling_factor": 4
      }
    }
  }
}
--------------------------------------------------
// CONSOLE
// TEST[continued]

[float]
==== Sigmoid

This 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 in +(0, 1)+.

`exponent` must be positive, but is typically in +[0.5, 1]+. A good value should
be computed via traning. If you don't have the opportunity to do so, we recommend
that you stick to the `saturation` function instead.

[source,js]
--------------------------------------------------
GET test/_search
{
  "query": {
    "feature": {
      "field": "pagerank",
      "sigmoid": {
        "pivot": 7,
        "exponent": 0.6
      }
    }
  }
}
--------------------------------------------------
// CONSOLE
// TEST[continued]