Change `rational` to `saturation` in script_score (#37766)

This change of the function name is necessary for conformity
with feature queries.

Closes #37714

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

@@ -52,13 +52,13 @@ 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.
 
-===== rational
-`rational(value,k) = value/(k + value)`
+===== saturation
+`saturation(value,k) = value/(k + value)`
 
 [source,js]
 --------------------------------------------------
 "script" : {
-    "source" : "rational(doc['likes'].value, 1)"
+    "source" : "saturation(doc['likes'].value, 1)"
 }
 --------------------------------------------------
 // NOTCONSOLE
@@ -78,21 +78,22 @@ to be the most efficient by using the internal mechanisms.
 [[random-functions]]
 ===== Random functions
 There are two predefined ways to produce random values:
+`randomNotReproducible` and `randomReproducible`.
 
-1. `randomNotReproducible()` uses `java.util.Random` class
+`randomNotReproducible()` uses `java.util.Random` class
 to generate a random value of the type `long`.
 The generated values are not reproducible between requests' invocations.
 
-    [source,js]
-    --------------------------------------------------
-    "script" : {
-        "source" : "randomNotReproducible()"
-    }
-    --------------------------------------------------
-    // NOTCONSOLE
+[source,js]
+--------------------------------------------------
+"script" : {
+    "source" : "randomNotReproducible()"
+}
+--------------------------------------------------
+// NOTCONSOLE
 
 
-2. `randomReproducible(String seedValue, int seed)` produces
+`randomReproducible(String seedValue, int seed)` produces
 reproducible random values of type `long`. This function requires
 more computational time and memory than the non-reproducible version.
 
@@ -102,13 +103,13 @@ in the memory. For example, values of the document's `_seq_no` field
 is a good candidate, as documents on the same shard have unique values
 for the `_seq_no` field.
 
-    [source,js]
-    --------------------------------------------------
-    "script" : {
-        "source" : "randomReproducible(Long.toString(doc['_seq_no'].value), 100)"
-    }
-    --------------------------------------------------
-    // NOTCONSOLE
+[source,js]
+--------------------------------------------------
+"script" : {
+    "source" : "randomReproducible(Long.toString(doc['_seq_no'].value), 100)"
+}
+--------------------------------------------------
+// NOTCONSOLE
 
 
 A drawback of using `_seq_no` is that generated values change if
@@ -121,13 +122,13 @@ you can use a field with unique values across shards,
 such as  `_id`, but watch out for the memory usage as all
 these unique values need to be loaded into memory.
 
-    [source,js]
-    --------------------------------------------------
-    "script" : {
-        "source" : "randomReproducible(doc['_id'].value, 100)"
-    }
-    --------------------------------------------------
-    // NOTCONSOLE
+[source,js]
+--------------------------------------------------
+"script" : {
+    "source" : "randomReproducible(doc['_id'].value, 100)"
+}
+--------------------------------------------------
+// NOTCONSOLE
 
 
 [[decay-functions]]
@@ -152,7 +153,7 @@ You can read more about decay functions
 }
 --------------------------------------------------
 // NOTCONSOLE
-<1> Use `params` to compile a script only once for different values of parameters
+<1> Using `params` allows to compile the script only once, even if params change.
 
 
 ===== Decay functions for geo fields

modules/lang-painless/src/main/resources/org/elasticsearch/painless/spi/org.elasticsearch.score.txt

@@ -20,7 +20,7 @@
 # This file contains a whitelist for functions to be used in Score context
 
 static_import {
-    double rational(double, double) from_class org.elasticsearch.script.ScoreScriptUtils
+    double saturation(double, double) from_class org.elasticsearch.script.ScoreScriptUtils
     double sigmoid(double, double, double) from_class org.elasticsearch.script.ScoreScriptUtils
     double randomReproducible(String, int) from_class org.elasticsearch.script.ScoreScriptUtils
     double randomNotReproducible()  bound_to org.elasticsearch.script.ScoreScriptUtils$RandomNotReproducible

modules/lang-painless/src/test/resources/rest-api-spec/test/painless/80_script_score.yml

@@ -5,6 +5,77 @@ setup:
     version: " - 6.99.99"
     reason: "script score query was introduced in 7.0.0"
 
+---
+"Math functions":
+    - do:
+        indices.create:
+            index: test
+            body:
+                settings:
+                    number_of_shards: 2
+                mappings:
+                    _doc:
+                        properties:
+                            dval:
+                                type: double
+    - do:
+        index:
+            index: test
+            type: _doc
+            id: d1
+            body: {"dval": 10}
+    - do:
+        index:
+            index: test
+            type: _doc
+            id: d2
+            body: {"dval": 100}
+    - do:
+        index:
+            index: test
+            type: _doc
+            id: d3
+            body: {"dval": 1000}
+
+    - do:
+        indices.refresh: {}
+
+    - do:
+        search:
+            rest_total_hits_as_int: true
+            index: test
+            body:
+                query:
+                    script_score:
+                        query: {match_all: {} }
+                        script:
+                            source: "saturation(doc['dval'].value, params.k)"
+                            params:
+                                k : 100
+    - match: { hits.total: 3 }
+    - match: { hits.hits.0._id: d3 }
+    - match: { hits.hits.1._id: d2 }
+    - match: { hits.hits.2._id: d1 }
+
+
+    - do:
+        search:
+            rest_total_hits_as_int: true
+            index: test
+            body:
+                query:
+                    script_score:
+                        query: {match_all: {} }
+                        script:
+                            source: "sigmoid(doc['dval'].value, params.k, params.a)"
+                            params:
+                                k: 100
+                                a: 2
+    - match: { hits.total: 3 }
+    - match: { hits.hits.0._id: d3 }
+    - match: { hits.hits.1._id: d2 }
+    - match: { hits.hits.2._id: d1 }
+
 ---
 "Random functions":
     - do:

server/src/main/java/org/elasticsearch/script/ScoreScriptUtils.java

@@ -41,7 +41,7 @@ public final class ScoreScriptUtils {
 
     /****** STATIC FUNCTIONS that can be used by users for score calculations **/
 
-    public static double rational(double value, double k) {
+    public static double saturation(double value, double k) {
         return value/ (k + value);
     }