From 03600e4e1253777b2a59131a3213cca5e99bc554 Mon Sep 17 00:00:00 2001 From: James Rodewig Date: Thu, 21 Nov 2019 08:53:56 -0500 Subject: [PATCH] [DOCS] Document `script_score` float precision limit (#49402) All document scores are positive 32-bit floating point numbers. However, this wasn't previously documented. This can result in surprising behavior, such as precision loss, for users when customizing scores using the function score query. This commit updates an existing admonition in the function score query docs to document the 32-bits precision limit. It also updates the search API reference docs to note that `_score` is a 32-bit float. --- .../reference/query-dsl/function-score-query.asciidoc | 11 +++++++++-- docs/reference/search/search.asciidoc | 6 +++--- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/reference/query-dsl/function-score-query.asciidoc b/docs/reference/query-dsl/function-score-query.asciidoc index 12cc2c1397196..371ba5e638145 100644 --- a/docs/reference/query-dsl/function-score-query.asciidoc +++ b/docs/reference/query-dsl/function-score-query.asciidoc @@ -153,8 +153,15 @@ GET /_search -------------------------------------------------- // TEST[setup:twitter] -NOTE: Scores produced by the `script_score` function must be non-negative, -otherwise an error will be thrown. +[IMPORTANT] +==== +In {es}, all document scores are positive 32-bit floating point numbers. + +If the `script_score` function produces a score with greater precision, it is +converted to the nearest 32-bit float. + +Similarly, scores must be non-negative. Otherwise, {es} returns an error. +==== On top of the different scripting field values and expression, the `_score` script parameter can be used to retrieve the score based on the diff --git a/docs/reference/search/search.asciidoc b/docs/reference/search/search.asciidoc index 87be5bcd7ef5c..378ce1a281361 100644 --- a/docs/reference/search/search.asciidoc +++ b/docs/reference/search/search.asciidoc @@ -309,7 +309,7 @@ Returned values are: (Float) Highest returned document `_score`. + -The `_score` parameter is a floating point number +The `_score` parameter is a 32-bit floating point number used to determine the relevance of the returned document. + This parameter value is `null` for requests @@ -325,8 +325,8 @@ Returned parameters include: deprecated:[7.0.0, Types are deprecated and are in the process of being removed. See <>.] * `_id`: Unique identifier for the returned document. This ID is only unique within the returned index. -* `_score`: Floating point number - used to determine the relevance of the returned document. +* `_score`: Positive 32-bit floating point number used to determine the + relevance of the returned document. * `_source`: Object containing the original JSON body passed for the document at index time. --