Skip to content

Commit

Permalink
Recommend use of ln1p/log1p to avoid negative scores (#41610)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
gwbrown authored May 3, 2019
1 parent e14aeb2 commit bb6d36a
Showing 1 changed file with 15 additions and 8 deletions.
23 changes: 15 additions & 8 deletions docs/reference/query-dsl/function-score-query.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -305,10 +305,14 @@ There are a number of options for the `field_value_factor` function:
| Modifier | Meaning

| `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
| `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
| `ln2p` | Add 2 to the field value and take the natural logarithm
| `square` | Square the field value (multiply it by itself)
Expand All @@ -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
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
is an illegal operation, and an exception will be thrown. Be sure to limit the
values of the field with a range filter to avoid this, or use `log1p` and
`ln1p`.
NOTE: Keep in mind that taking the log() of 0, or the square root of a
negative number is an illegal operation, and an exception will be thrown. Be
sure to limit the values of the field with a range filter to avoid this, or use
`log1p` and `ln1p`.

NOTE: Scores produced by the `field_value_score` function must be non-negative,
otherwise an error will be thrown.

[[function-decay]]
==== Decay functions
Expand Down

0 comments on commit bb6d36a

Please sign in to comment.