IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› › ›

Script score query

edit

Script score query

edit

Uses a script to provide a custom score for returned documents.

The script_score query is useful if, for example, a scoring function is expensive and you only need to calculate the score of a filtered set of documents.

Example request

edit

The following script_score query assigns each returned document a score equal to the likes field value divided by 10.

GET /_search
{
    "query" : {
        "script_score" : {
            "query" : {
                "match": { "message": "elasticsearch" }
            },
            "script" : {
                "source" : "doc['likes'].value / 10 "
            }
        }
     }
}

Top-level parameters for `script_score`

edit

query: (Required, query object) Query used to return documents.
script: (Required, script object) Script used to compute the score of documents returned by the query.

Final relevance scores from the script_score query cannot be negative. To support certain search optimizations, Lucene requires scores be positive or 0.
min_score: (Optional, float) Documents with a relevance score lower than this floating point number are excluded from the search results.

Notes

edit

Use relevance scores in a script

edit

Within a script, you can access the _score variable which represents the current relevance score of a document.

Predefined functions

edit

You can use any of the available painless functions in your script. You can also use the following predefined functions to customize scoring:

We suggest using these predefined functions instead of writing your own. These functions take advantage of efficiencies from Elasticsearch' internal mechanisms.

Saturation

edit

saturation(value,k) = value/(k + value)

"script" : {
    "source" : "saturation(doc['likes'].value, 1)"
}

Sigmoid

edit

sigmoid(value, k, a) = value^a/ (k^a + value^a)

"script" : {
    "source" : "sigmoid(doc['likes'].value, 2, 1)"
}

Random score function

edit

random_score function generates scores that are uniformly distributed from 0 up to but not including 1.

randomScore function has the following syntax: randomScore(<seed>, <fieldName>). It has a required parameter - seed as an integer value, and an optional parameter - fieldName as a string value.

"script" : {
    "source" : "randomScore(100, '_seq_no')"
}

If the fieldName parameter is omitted, the internal Lucene document ids will be used as a source of randomness. This is very efficient, but unfortunately not reproducible since documents might be renumbered by merges.

"script" : {
    "source" : "randomScore(100)"
}

Note that documents that are within the same shard and have the same value for field will get the same score, so it is usually desirable to use a field that has unique values for all documents across a shard. A good default choice might be to use the _seq_no field, whose only drawback is that scores will change if the document is updated since update operations also update the value of the _seq_no field.

Decay functions for numeric fields

edit

You can read more about decay functions here.

double decayNumericLinear(double origin, double scale, double offset, double decay, double docValue)
double decayNumericExp(double origin, double scale, double offset, double decay, double docValue)
double decayNumericGauss(double origin, double scale, double offset, double decay, double docValue)

"script" : {
    "source" : "decayNumericLinear(params.origin, params.scale, params.offset, params.decay, doc['dval'].value)",
    "params": { 
        "origin": 20,
        "scale": 10,
        "decay" : 0.5,
        "offset" : 0
    }
}

Using params allows to compile the script only once, even if params change.

Decay functions for geo fields

edit

double decayGeoLinear(String originStr, String scaleStr, String offsetStr, double decay, GeoPoint docValue)
double decayGeoExp(String originStr, String scaleStr, String offsetStr, double decay, GeoPoint docValue)
double decayGeoGauss(String originStr, String scaleStr, String offsetStr, double decay, GeoPoint docValue)

"script" : {
    "source" : "decayGeoExp(params.origin, params.scale, params.offset, params.decay, doc['location'].value)",
    "params": {
        "origin": "40, -70.12",
        "scale": "200km",
        "offset": "0km",
        "decay" : 0.2
    }
}

Decay functions for date fields

edit

double decayDateLinear(String originStr, String scaleStr, String offsetStr, double decay, JodaCompatibleZonedDateTime docValueDate)
double decayDateExp(String originStr, String scaleStr, String offsetStr, double decay, JodaCompatibleZonedDateTime docValueDate)
double decayDateGauss(String originStr, String scaleStr, String offsetStr, double decay, JodaCompatibleZonedDateTime docValueDate)

"script" : {
    "source" : "decayDateGauss(params.origin, params.scale, params.offset, params.decay, doc['date'].value)",
    "params": {
        "origin": "2008-01-01T01:00:00Z",
        "scale": "1h",
        "offset" : "0",
        "decay" : 0.5
    }
}

Decay functions on dates are limited to dates in the default format and default time zone. Also calculations with now are not supported.

Faster alternatives

edit

The script_score query calculates the score for every matching document, or hit. There are faster alternative query types that can efficiently skip non-competitive hits:

If you want to boost documents on some static fields, use the rank_feature query.
If you want to boost documents closer to a date or geographic point, use the distance_feature query.

Transition from the function score query

edit

We are deprecating the function_score query. We recommend using the script_score query instead.

You can implement the following functions from the function_score query using the script_score query:

`script_score`

edit

What you used in script_score of the Function Score query, you can copy into the Script Score query. No changes here.

`weight`

edit

weight function can be implemented in the Script Score query through the following script:

"script" : {
    "source" : "params.weight * _score",
    "params": {
        "weight": 2
    }
}

`random_score`

edit

Use randomScore function as described in random score function.

`field_value_factor`

edit

field_value_factor function can be easily implemented through script:

"script" : {
    "source" : "Math.log10(doc['field'].value * params.factor)",
    params" : {
        "factor" : 5
    }
}

For checking if a document has a missing value, you can use doc['field'].size() == 0. For example, this script will use a value 1 if a document doesn’t have a field field:

"script" : {
    "source" : "Math.log10((doc['field'].size() == 0 ? 1 : doc['field'].value()) * params.factor)",
    params" : {
        "factor" : 5
    }
}

This table lists how field_value_factor modifiers can be implemented through a script:

Modifier	Implementation in Script Score
`none`	-
`log`	`Math.log10(doc['f'].value)`
`log1p`	`Math.log10(doc['f'].value + 1)`
`log2p`	`Math.log10(doc['f'].value + 2)`
`ln`	`Math.log(doc['f'].value)`
`ln1p`	`Math.log(doc['f'].value + 1)`
`ln2p`	`Math.log(doc['f'].value + 2)`
`square`	`Math.pow(doc['f'].value, 2)`
`sqrt`	`Math.sqrt(doc['f'].value)`
`reciprocal`	`1.0 / doc['f'].value`

`decay` functions

edit

The script_score query has equivalent decay functions that can be used in script.

« Script query Wrapper query »

Script score query

Script score query

Example request

Top-level parameters for script_score

Notes

Use relevance scores in a script

Predefined functions

Saturation

Sigmoid

Random score function

Decay functions for numeric fields

Decay functions for geo fields

Decay functions for date fields

Faster alternatives

Transition from the function score query

script_score

weight

random_score

field_value_factor

decay functions

Top-level parameters for `script_score`

`script_score`

`weight`

`random_score`

`field_value_factor`

`decay` functions