From 138865a58e3c7aa222a2ff586ae144028d63ed26 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Thu, 1 Aug 2019 12:06:34 -0400 Subject: [PATCH] [DOCS] Reformat script score query (#45087) --- .../query-dsl/script-score-query.asciidoc | 131 ++++++++++++------ 1 file changed, 86 insertions(+), 45 deletions(-) diff --git a/docs/reference/query-dsl/script-score-query.asciidoc b/docs/reference/query-dsl/script-score-query.asciidoc index 9f6db700e2b..fce58709f15 100644 --- a/docs/reference/query-dsl/script-score-query.asciidoc +++ b/docs/reference/query-dsl/script-score-query.asciidoc @@ -4,18 +4,15 @@ Script score ++++ -The `script_score` allows you to modify the score of documents that are -retrieved by a query. This can be useful if, for example, a score -function is computationally expensive and it is sufficient to compute -the score on a filtered set of documents. +Uses a <> to provide a custom score for returned +documents. -To use `script_score`, you have to define a query and a script - -a function to be used to compute a new score for each document returned -by the query. For more information on scripting see -<>. +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. -Here is an example of using `script_score` to assign each matched document -a score equal to the number of likes divided by 10: + +[[script-score-query-ex-request]] +==== Example request +The following `script_score` query assigns each returned document a score equal to the `likes` field value divided by `10`. [source,js] -------------------------------------------------- @@ -35,23 +32,57 @@ GET /_search -------------------------------------------------- // CONSOLE -==== Accessing the score of a document within a script + +[[script-score-top-level-params]] +==== Top-level parameters for `script_score` +`query`:: +(Required, query object) Query used to return documents. + +`script`:: ++ +-- +(Required, <>) Script used to compute the score of documents returned by the `query`. + +IMPORTANT: 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 <> lower +than this floating point number are excluded from the search results. + + +[[script-score-query-notes]] +==== Notes + +[[script-score-access-scores]] +===== Use relevance scores in a script Within a script, you can {ref}/modules-scripting-fields.html#scripting-score[access] the `_score` variable which represents the current relevance score of a document. +[[script-score-predefined-functions]] +===== Predefined functions +You can use any of the available {painless}/painless-contexts.html[painless +functions] in your `script`. You can also use the following predefined functions +to customize scoring: -==== Predefined functions within a Painless script -You can use any of the available -<> in the painless script. -Besides these functions, there are a number of predefined functions -that can help you with scoring. We suggest you to use them instead of -rewriting equivalent functions of your own, as these functions try -to be the most efficient by using the internal mechanisms. +* <> +* <> +* <> +* <> +* <> +* <> +* <> -===== saturation +We suggest using these predefined functions instead of writing your own. +These functions take advantage of efficiencies from {es}' internal mechanisms. + +[[script-score-saturation]] +====== Saturation `saturation(value,k) = value/(k + value)` [source,js] @@ -62,7 +93,8 @@ to be the most efficient by using the internal mechanisms. -------------------------------------------------- // NOTCONSOLE -===== sigmoid +[[script-score-sigmoid]] +====== Sigmoid `sigmoid(value, k, a) = value^a/ (k^a + value^a)` [source,js] @@ -74,7 +106,7 @@ to be the most efficient by using the internal mechanisms. // NOTCONSOLE [[random-score-function]] -===== Random score function +====== Random score function `random_score` function generates scores that are uniformly distributed from 0 up to but not including 1. @@ -104,7 +136,6 @@ by merges. -------------------------------------------------- // NOTCONSOLE - 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. @@ -114,7 +145,7 @@ updated since update operations also update the value of the `_seq_no` field. [[decay-functions-numeric-fields]] -===== Decay functions for numeric fields +====== Decay functions for numeric fields You can read more about decay functions {ref}/query-dsl-function-score-query.html#function-decay[here]. @@ -137,8 +168,8 @@ You can read more about decay functions // NOTCONSOLE <1> Using `params` allows to compile the script only once, even if params change. - -===== Decay functions for geo fields +[[decay-functions-geo-fields]] +====== Decay functions for geo fields * `double decayGeoLinear(String originStr, String scaleStr, String offsetStr, double decay, GeoPoint docValue)` @@ -160,8 +191,8 @@ You can read more about decay functions -------------------------------------------------- // NOTCONSOLE - -===== Decay functions for date fields +[[decay-functions-date-fields]] +====== Decay functions for date fields * `double decayDateLinear(String originStr, String scaleStr, String offsetStr, double decay, JodaCompatibleZonedDateTime docValueDate)` @@ -186,33 +217,43 @@ You can read more about decay functions NOTE: Decay functions on dates are limited to dates in the default format and default time zone. Also calculations with `now` are not supported. -===== Functions for vector fields +[[script-score-functions-vector-fields]] +====== Functions for vector fields <> are accessible through `script_score` query. -==== Faster alternatives -Script Score Query calculates the score for every hit (matching document). -There are faster alternative query types that can efficiently skip -non-competitive hits: +[[script-score-faster-alt]] +===== Faster alternatives +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 - <>. +* If you want to boost documents on some static fields, use the + <> query. + * If you want to boost documents closer to a date or geographic point, use the + <> query. +[[script-score-function-score-transition]] +===== Transition from the function score query +We are deprecating the <> +query. We recommend using the `script_score` query instead. -==== Transition from Function Score Query -We are deprecating <>, and -Script Score Query will be a substitute for it. +You can implement the following functions from the `function_score` query using +the `script_score` query: -Here we describe how Function Score Query's functions can be -equivalently implemented in Script Score Query: +* <> +* <> +* <> +* <> +* <> [[script-score]] -===== `script_score` +====== `script_score` What you used in `script_score` of the Function Score query, you can copy into the Script Score query. No changes here. [[weight]] -===== `weight` +====== `weight` `weight` function can be implemented in the Script Score query through the following script: @@ -228,13 +269,13 @@ the following script: // NOTCONSOLE [[random-score]] -===== `random_score` +====== `random_score` Use `randomScore` function as described in <>. [[field-value-factor]] -===== `field_value_factor` +====== `field_value_factor` `field_value_factor` function can be easily implemented through script: [source,js] @@ -284,8 +325,8 @@ through a script: |======================================================================= [[decay-functions]] -===== `decay functions` -Script Score query has equivalent <> +====== `decay` functions +The `script_score` query has equivalent <> that can be used in script. include::{es-repo-dir}/vectors/vector-functions.asciidoc[]