[DOCS] Reformat script score query (#45087)

Author: jrodewig

docs/reference/query-dsl/script-score-query.asciidoc

@@ -4,18 +4,15 @@
 <titleabbrev>Script score</titleabbrev>
 ++++
 
-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 <<modules-scripting,script>> 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
-<<modules-scripting, scripting documentation>>.
+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, <<modules-scripting-using,script object>>) 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 <<relevance-scores,relevance score>> 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.
 
-
-==== Predefined functions within a Painless script
-You can use any of the available
-<<painless-api-reference, painless functions>> 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
+[[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:
+
+* <<script-score-saturation>>
+* <<script-score-sigmoid>>
+* <<random-score-function>>
+* <<decay-functions-numeric-fields>>
+* <<decay-functions-geo-fields>>
+* <<decay-functions-date-fields>>
+* <<script-score-functions-vector-fields>>
+
+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
 <<vector-functions, 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
- <<query-dsl-rank-feature-query, Rank Feature Query>>.
+* If you want to boost documents on some static fields, use the 
+ <<query-dsl-rank-feature-query, `rank_feature`>> query.
+ * If you want to boost documents closer to a date or geographic point, use the
+ <<query-dsl-distance-feature-query, `distance_feature`>> query.
 
+[[script-score-function-score-transition]]
+===== Transition from the function score query
+We are deprecating the <<query-dsl-function-score-query, `function_score`>>
+query. We recommend using the `script_score` query instead.
 
-==== Transition from Function Score Query
-We are deprecating <<query-dsl-function-score-query, Function Score>>, 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>>
+* <<weight>>
+* <<random-score>>
+* <<field-value-factor>>
+* <<decay-functions>>
 
 [[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 <<random-score-function, random score function>>.
 
 [[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, decay functions>>
+====== `decay` functions
+The `script_score` query has equivalent <<decay-functions, decay functions>>
 that can be used in script.
 
 include::{es-repo-dir}/vectors/vector-functions.asciidoc[]