retain the scores of portions of an ES|QL query, via a score function (elastic#127551)

Author: tteofili

docs/reference/query-languages/esql/_snippets/functions/description/score.md

@@ -0,0 +1,127 @@
+###############################################
+# Tests for Score function
+#
+
+scoreSingle
+required_capability: metadata_score
+required_capability: score_function
+required_capability: match_function
+
+// tag::score-function[]
+FROM books METADATA _score
+| WHERE match(title, "Return") AND match(author, "Tolkien")
+| EVAL first_score = score(match(title, "Return")) 
+// end::score-function[]
+| KEEP book_no, title, _score, first_score
+| SORT book_no
+| LIMIT 5
+;
+
+// tag::score-single-result[]
+book_no:keyword | title:text                                                       | _score:double      | first_score:double
+2714            | Return of the King Being the Third Part of The Lord of the Rings | 3.1309072971343994 | 1.9245924949645996
+7350            | Return of the Shadow                                             | 4.8434343338012695 | 3.5432329177856445
+// end::score-single-result[]
+;
+
+scoreSingleNoMetadata
+required_capability: score_function
+required_capability: match_function
+
+FROM books
+| WHERE match(title, "Return") AND match(author, "Tolkien")
+| EVAL first_score = score(match(title, "Return")) 
+| KEEP book_no, title, first_score
+| SORT book_no
+| LIMIT 5
+;
+
+book_no:keyword | title:text                                                       | first_score:double 
+2714            | Return of the King Being the Third Part of The Lord of the Rings | 1.9245924949645996
+7350            | Return of the Shadow                                             | 3.5432329177856445
+;
+
+scoreAfterEval
+required_capability: score_function
+required_capability: metadata_score
+required_capability: match_function
+
+FROM books METADATA _score
+| EVAL stars = to_long(ratings / 2.0)
+| EVAL s1 = score(match(author, "William")) 
+| WHERE match(author, "Faulkner")
+| SORT book_no 
+| KEEP book_no, author, stars, s1
+| limit 5;
+
+book_no:keyword | author:text                                        | stars:long | s1:double
+2378            | [Carol Faulkner, Holly Byers Ochoa, Lucretia Mott] | 3          | 0.0
+2713            | William Faulkner                                   | 2          | 1.9043500423431396
+2847            | Colleen Faulkner                                   | 3          | 0.0
+2883            | William Faulkner                                   | 2          | 1.9043500423431396
+3293            | Danny Faulkner                                     | 2          | 0.0
+;
+
+scoreMatchWithFilterConjunction
+required_capability: score_function
+required_capability: match_function
+
+FROM books
+| WHERE match(title, "Return") AND match(author, "Tolkien")
+| EVAL s1 = score(match(title, "Rings") and ratings > 4.6)
+| KEEP book_no, title, s1
+| SORT book_no
+| LIMIT 5;
+
+book_no:keyword | title:text                                                       | s1:double
+2714            | Return of the King Being the Third Part of The Lord of the Rings | 1.9245924949645996
+7350            | Return of the Shadow                                             | 0.0
+;
+
+scoreMatchWithDisjunction
+required_capability: score_function
+required_capability: match_function
+
+FROM books
+| WHERE match(title, "Return") AND match(author, "Tolkien")
+| EVAL s1 = score(match(title, "Rings") or match(title, "Shadow"))
+| KEEP book_no, title, s1
+| SORT book_no
+| LIMIT 5;
+
+book_no:keyword | title:text                                                       | s1:double
+2714            | Return of the King Being the Third Part of The Lord of the Rings | 1.9245924949645996
+7350            | Return of the Shadow                                             | 3.5432329177856445
+;
+
+scoreMatchWithDisjunctionAndFilter
+required_capability: score_function
+required_capability: match_function
+
+FROM books
+| WHERE match(title, "Return") AND match(author, "Tolkien")
+| EVAL s1 = score(match(title, "Rings") or match(title, "Shadow") and ratings > 4.6)
+| KEEP book_no, title, s1
+| SORT book_no
+| LIMIT 5;
+
+book_no:keyword | title:text                                                       | s1:double
+2714            | Return of the King Being the Third Part of The Lord of the Rings | 1.9245924949645996
+7350            | Return of the Shadow                                             | 3.5432329177856445
+;
+
+scoreMatchDisjunctionNonPushable
+required_capability: score_function
+required_capability: match_function
+
+FROM books
+| WHERE match(title, "Return") AND match(author, "Tolkien")
+| EVAL s1 = score(match(title, "Rings") or ratings > 4.6)
+| KEEP book_no, title, s1
+| SORT book_no
+| LIMIT 5;
+
+book_no:keyword | title:text                                                       | s1:double
+2714            | Return of the King Being the Third Part of The Lord of the Rings | 1.9245924949645996
+7350            | Return of the Shadow                                             | 0.0
+;