honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Recommend use of ln1p/log1p to avoid negative scores (#41610) 

As negative scores will now cause an error, and it is easy to
accidentally produce negative scores with some of the built-in modifiers
(especially `ln` and `log`), this adjusts the documentation to more
strongly recommend the use of `ln1p` and `log1p` instead.

Also corrects some awkward formatting on the note sections following the
table.
This commit is contained in:
Gordon Brown 2019-05-03 09:10:29 -06:00 committed by GitHub
parent 03c959f188
commit 9a4cab9f77
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 15 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docs/reference/query-dsl/function-score-query.asciidoc
View File

@ -305,10 +305,14 @@ There are a number of options for the `field_value_factor` function:
| Modifier | Meaning | Modifier | Meaning
| `none` | Do not apply any multiplier to the field value | `none` | Do not apply any multiplier to the field value
| `log` | Take the https://en.wikipedia.org/wiki/Common_logarithm[common logarithm] of the field value | `log` | Take the https://en.wikipedia.org/wiki/Common_logarithm[common logarithm] of the field value.
Because this function will return a negative value and cause an error if used on values
between 0 and 1, it is recommended to use `log1p` instead.
| `log1p` | Add 1 to the field value and take the common logarithm | `log1p` | Add 1 to the field value and take the common logarithm
| `log2p` | Add 2 to the field value and take the common logarithm | `log2p` | Add 2 to the field value and take the common logarithm
| `ln` | Take the https://en.wikipedia.org/wiki/Natural_logarithm[natural logarithm] of the field value | `ln` | Take the https://en.wikipedia.org/wiki/Natural_logarithm[natural logarithm] of the field value.
Because this function will return a negative value and cause an error if used on values
between 0 and 1, it is recommended to use `ln1p` instead.
| `ln1p` | Add 1 to the field value and take the natural logarithm | `ln1p` | Add 1 to the field value and take the natural logarithm
| `ln2p` | Add 2 to the field value and take the natural logarithm | `ln2p` | Add 2 to the field value and take the natural logarithm
| `square` | Square the field value (multiply it by itself) | `square` | Square the field value (multiply it by itself)
@ -321,14 +325,17 @@ There are a number of options for the `field_value_factor` function:
Value used if the document doesn't have that field. The modifier Value used if the document doesn't have that field. The modifier
and factor are still applied to it as though it were read from the document. and factor are still applied to it as though it were read from the document.
NOTE: Scores produced by the `field_value_score` function must be
non-negative, otherwise an error will be thrown. The `log` and `ln` modifiers
will produce negative values if used on values between 0 and 1. Be sure to limit
the values of the field with a range filter to avoid this, or use `log1p` and
`ln1p`.
Keep in mind that taking the log() of 0, or the square root of a negative number NOTE: Keep in mind that taking the log() of 0, or the square root of a
is an illegal operation, and an exception will be thrown. Be sure to limit the negative number is an illegal operation, and an exception will be thrown. Be
values of the field with a range filter to avoid this, or use `log1p` and sure to limit the values of the field with a range filter to avoid this, or use
`ln1p`. `log1p` and `ln1p`.
NOTE: Scores produced by the `field_value_score` function must be non-negative,
otherwise an error will be thrown.
[[function-decay]] [[function-decay]]
==== Decay functions ==== Decay functions