Skip to content

Commit 03600e4

Browse files
committed
[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.
1 parent 3eb577f commit 03600e4

File tree

2 files changed

+12
-5
lines changed

2 files changed

+12
-5
lines changed

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

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -153,8 +153,15 @@ GET /_search
153153
--------------------------------------------------
154154
// TEST[setup:twitter]
155155

156-
NOTE: Scores produced by the `script_score` function must be non-negative,
157-
otherwise an error will be thrown.
156+
[IMPORTANT]
157+
====
158+
In {es}, all document scores are positive 32-bit floating point numbers.
159+
160+
If the `script_score` function produces a score with greater precision, it is
161+
converted to the nearest 32-bit float.
162+
163+
Similarly, scores must be non-negative. Otherwise, {es} returns an error.
164+
====
158165

159166
On top of the different scripting field values and expression, the
160167
`_score` script parameter can be used to retrieve the score based on the

docs/reference/search/search.asciidoc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -309,7 +309,7 @@ Returned values are:
309309
(Float)
310310
Highest returned document `_score`.
311311
+
312-
The `_score` parameter is a floating point number
312+
The `_score` parameter is a 32-bit floating point number
313313
used to determine the relevance of the returned document.
314314
+
315315
This parameter value is `null` for requests
@@ -325,8 +325,8 @@ Returned parameters include:
325325
deprecated:[7.0.0, Types are deprecated and are in the process of being removed. See <<removal-of-types>>.]
326326
* `_id`: Unique identifier for the returned document.
327327
This ID is only unique within the returned index.
328-
* `_score`: Floating point number
329-
used to determine the relevance of the returned document.
328+
* `_score`: Positive 32-bit floating point number used to determine the
329+
relevance of the returned document.
330330
* `_source`: Object containing the original JSON body
331331
passed for the document at index time.
332332
--

0 commit comments

Comments
 (0)