Skip to content

Commit

Permalink
[DOCS] Document script_score float precision limit (#49402)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
jrodewig committed Nov 21, 2019
1 parent 1d30b01 commit 9b341b6
Show file tree
Hide file tree
Showing 2 changed files with 12 additions and 5 deletions.
11 changes: 9 additions & 2 deletions docs/reference/query-dsl/function-score-query.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions docs/reference/search/search.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -325,8 +325,8 @@ Returned parameters include:
deprecated:[7.0.0, Types are deprecated and are in the process of being removed. See <<removal-of-types>>.]
* `_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.
--
Expand Down

0 comments on commit 9b341b6

Please sign in to comment.