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
+===== saturation
-`rational(value,k) = value/(k + value)`
+`saturation(value,k) = value/(k + value)`
 
 [source,js]
 --------------------------------------------------
 "script" : {
-    "source" : "rational(doc['likes'].value, 1)"
+    "source" : "saturation(doc['likes'].value, 1)"
 }
 --------------------------------------------------
 // NOTCONSOLE
@@ -78,8 +78,9 @@ 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.
 
@@ -92,7 +93,7 @@ The generated values are not reproducible between requests' invocations.
 // 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.
 
@@ -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);
     }