Clinton Gormley
parent
f5f73259e4
commit
765ac45168
|
|
@ -17,10 +17,11 @@ by the query.
|
|||
"function_score": {
|
||||
"query": {},
|
||||
"boost": "boost for the whole query",
|
||||
"FUNCTION": {},
|
||||
"FUNCTION": {}, <1>
|
||||
"boost_mode":"(multiply|replace|...)"
|
||||
}
|
||||
--------------------------------------------------
|
||||
<1> See <<score-functions>> for a list of supported functions.
|
||||
|
||||
Furthermore, several functions can be combined. In this case one can
|
||||
optionally choose to apply the function only if a document matches a
|
||||
|
|
@ -34,11 +35,11 @@ given filtering query
|
|||
"functions": [
|
||||
{
|
||||
"filter": {},
|
||||
"FUNCTION": {},
|
||||
"FUNCTION": {}, <1>
|
||||
"weight": number
|
||||
},
|
||||
{
|
||||
"FUNCTION": {}
|
||||
"FUNCTION": {} <1>
|
||||
},
|
||||
{
|
||||
"filter": {},
|
||||
|
|
@ -51,6 +52,7 @@ given filtering query
|
|||
"min_score" : number
|
||||
}
|
||||
--------------------------------------------------
|
||||
<1> See <<score-functions>> for a list of supported functions.
|
||||
|
||||
NOTE: The scores produced by the filtering query of each function do not matter.
|
||||
|
||||
|
|
@ -89,8 +91,17 @@ query. The parameter `boost_mode` defines how:
|
|||
By default, modifying the score does not change which documents match. To exclude
|
||||
documents that do not meet a certain score threshold the `min_score` parameter can be set to the desired score threshold.
|
||||
|
||||
[[score-functions]]
|
||||
|
||||
The `function_score` query provides several types of score functions.
|
||||
|
||||
* <<function-script-score,`script_score`>>
|
||||
* <<function-weight,`weight`>>
|
||||
* <<function-random,`random_score`>>
|
||||
* <<function-field-value-factor,`field_value_factor`>>
|
||||
* <<function-decay,decay functions>>: `gauss`, `linear`, `exp`
|
||||
|
||||
[[function-script-score]]
|
||||
==== Script score
|
||||
|
||||
The `script_score` function allows you to wrap another query and customize
|
||||
|
|
@ -131,6 +142,7 @@ Note that unlike the `custom_score` query, the
|
|||
score of the query is multiplied with the result of the script scoring. If
|
||||
you wish to inhibit this, set `"boost_mode": "replace"`
|
||||
|
||||
[[function-weight]]
|
||||
==== Weight
|
||||
|
||||
The `weight` score allows you to multiply the score by the provided
|
||||
|
|
@ -143,6 +155,7 @@ not.
|
|||
"weight" : number
|
||||
--------------------------------------------------
|
||||
|
||||
[[function-random]]
|
||||
==== Random
|
||||
|
||||
The `random_score` generates scores using a hash of the `_uid` field,
|
||||
|
|
@ -159,6 +172,7 @@ be a memory intensive operation since the values are unique.
|
|||
}
|
||||
--------------------------------------------------
|
||||
|
||||
[[function-field-value-factor]]
|
||||
==== Field Value factor
|
||||
|
||||
The `field_value_factor` function allows you to use a field from a document to
|
||||
|
|
@ -186,23 +200,33 @@ Which will translate into the following formula for scoring:
|
|||
|
||||
There are a number of options for the `field_value_factor` function:
|
||||
|
||||
[cols="<,<",options="header",]
|
||||
|=======================================================================
|
||||
| Parameter |Description
|
||||
|`field` |Field to be extracted from the document.
|
||||
|`factor` |Optional factor to multiply the field value with, defaults to 1.
|
||||
|`modifier` |Modifier to apply to the field value, can be one of: `none`, `log`,
|
||||
`log1p`, `log2p`, `ln`, `ln1p`, `ln2p`, `square`, `sqrt`, or `reciprocal`.
|
||||
Defaults to `none`.
|
||||
|`missing` |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.
|
||||
|=======================================================================
|
||||
[horizontal]
|
||||
`field`::
|
||||
|
||||
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`.
|
||||
Field to be extracted from the document.
|
||||
|
||||
`factor`::
|
||||
|
||||
Optional factor to multiply the field value with, defaults to `1`.
|
||||
|
||||
`modifier`::
|
||||
|
||||
Modifier to apply to the field value, can be one of: `none`, `log`,
|
||||
`log1p`, `log2p`, `ln`, `ln1p`, `ln2p`, `square`, `sqrt`, or `reciprocal`.
|
||||
Defaults to `none`.
|
||||
|
||||
`missing`::
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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`.
|
||||
|
||||
[[function-decay]]
|
||||
==== Decay functions
|
||||
|
||||
Decay functions score a document with a function that decays depending
|
||||
|
|
@ -218,8 +242,8 @@ decay function is specified as
|
|||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
"DECAY_FUNCTION": {
|
||||
"FIELD_NAME": {
|
||||
"DECAY_FUNCTION": { <1>
|
||||
"FIELD_NAME": { <2>
|
||||
"origin": "11, 12",
|
||||
"scale": "2km",
|
||||
"offset": "0km",
|
||||
|
|
@ -227,26 +251,26 @@ decay function is specified as
|
|||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
<1> The `DECAY_FUNCTION` should be one of `linear`, `exp`, or `gauss`.
|
||||
<2> The specified field must be a numeric, date, or geo-point field.
|
||||
|
||||
In the above example, the field is a <<mapping-geo-point-type>> and origin can be provided in geo format. `scale` and `offset` must be given with a unit in this case. If your field is a date field, you can set `scale` and `offset` as days, weeks, and so on. Example:
|
||||
|
||||
where `DECAY_FUNCTION` can be "linear", "exp" and "gauss" (see below). The specified field must be a numeric field. In the above example, the field is a <<mapping-geo-point-type>> and origin can be provided in geo format. `scale` and `offset` must be given with a unit in this case. If your field is a date field, you can set `scale` and `offset` as days, weeks, and so on. Example:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
"DECAY_FUNCTION": {
|
||||
"FIELD_NAME": {
|
||||
"origin": "2013-09-17",
|
||||
"gauss": {
|
||||
"date": {
|
||||
"origin": "2013-09-17", <1>
|
||||
"scale": "10d",
|
||||
"offset": "5d",
|
||||
"decay" : 0.5
|
||||
"offset": "5d", <2>
|
||||
"decay" : 0.5 <2>
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
|
||||
The format of the origin depends on the <<mapping-date-format>> defined in your mapping. If you do not define the origin, the current time is used.
|
||||
|
||||
|
||||
The `offset` and `decay` parameters are optional.
|
||||
<1> The date format of the origin depends on the <<mapping-date-format>> defined in
|
||||
your mapping. If you do not define the origin, the current time is used.
|
||||
<2> The `offset` and `decay` parameters are optional.
|
||||
|
||||
[horizontal]
|
||||
`origin`::
|
||||
|
|
@ -284,37 +308,45 @@ from the desired location.
|
|||
|
||||
In the second example, documents with a field value between 2013-09-12 and 2013-09-22 would get a weight of 1.0 and documents which are 15 days from that date a weight of 0.5.
|
||||
|
||||
|
||||
===== Supported decay functions
|
||||
|
||||
The `DECAY_FUNCTION` determines the shape of the decay:
|
||||
|
||||
[horizontal]
|
||||
`gauss`::
|
||||
|
||||
Normal decay, computed as:
|
||||
+
|
||||
--
|
||||
Normal decay, computed as:
|
||||
|
||||
image:images/Gaussian.png[]
|
||||
|
||||
where image:images/sigma.png[] is computed to assure that the score takes the value `decay` at distance `scale` from `origin`+-`offset`
|
||||
|
||||
image:images/sigma_calc.png[]
|
||||
|
||||
[horizontal]
|
||||
`exp`::
|
||||
See <<gauss-decay>> for graphs demonstrating the curve generated by the `gauss` function.
|
||||
|
||||
Exponential decay, computed as:
|
||||
--
|
||||
|
||||
`exp`::
|
||||
+
|
||||
--
|
||||
Exponential decay, computed as:
|
||||
|
||||
image:images/Exponential.png[]
|
||||
|
||||
where again the parameter image:images/lambda.png[] is computed to assure that the score takes the value `decay` at distance `scale` from `origin`+-`offset`
|
||||
|
||||
image:images/lambda_calc.png[]
|
||||
|
||||
[horizontal]
|
||||
`linear`::
|
||||
See <<exp-decay>> for graphs demonstrating the curve generated by the `exp` function.
|
||||
|
||||
Linear decay, computed as:
|
||||
--
|
||||
|
||||
`linear`::
|
||||
+
|
||||
--
|
||||
Linear decay, computed as:
|
||||
|
||||
image:images/Linear.png[].
|
||||
|
||||
|
||||
|
|
@ -325,12 +357,13 @@ image:images/s_calc.png[]
|
|||
In contrast to the normal and exponential decay, this function actually
|
||||
sets the score to 0 if the field value exceeds twice the user given
|
||||
scale value.
|
||||
--
|
||||
|
||||
For single functions the three decay functions together with their parameters can be visualized like this (the field in this example called "age"):
|
||||
|
||||
image:images/decay_2d.png[width=600]
|
||||
|
||||
===== Multiple values:
|
||||
===== Multi-values fields
|
||||
|
||||
If a field used for computing the decay contains multiple values, per default the value closest to the origin is chosen for determining the distance.
|
||||
This can be changed by setting `multi_value_mode`.
|
||||
|
|
@ -355,8 +388,7 @@ Example:
|
|||
--------------------------------------------------
|
||||
|
||||
|
||||
|
||||
===== Detailed example
|
||||
==== Detailed example
|
||||
|
||||
Suppose you are searching for a hotel in a certain town. Your budget is
|
||||
limited. Also, you would like the hotel to be close to the town center,
|
||||
|
|
@ -383,69 +415,72 @@ The function for `price` in this case would be
|
|||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
"DECAY_FUNCTION": {
|
||||
"gauss": { <1>
|
||||
"price": {
|
||||
"origin": "0",
|
||||
"scale": "20"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
<1> This decay function could also be `linear` or `exp`.
|
||||
|
||||
and for `location`:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
|
||||
"DECAY_FUNCTION": {
|
||||
"gauss": { <1>
|
||||
"location": {
|
||||
"origin": "11, 12",
|
||||
"scale": "2km"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
||||
where `DECAY_FUNCTION` can be "linear", "exp" and "gauss".
|
||||
<1> This decay function could also be `linear` or `exp`.
|
||||
|
||||
Suppose you want to multiply these two functions on the original score,
|
||||
the request would look like this:
|
||||
|
||||
[source,js]
|
||||
--------------------------------------------------
|
||||
curl 'localhost:9200/hotels/_search/' -d '{
|
||||
"query": {
|
||||
GET /hotels/_search/
|
||||
{
|
||||
"query": {
|
||||
"function_score": {
|
||||
"functions": [
|
||||
{
|
||||
"DECAY_FUNCTION": {
|
||||
"price": {
|
||||
"origin": "0",
|
||||
"scale": "20"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"DECAY_FUNCTION": {
|
||||
"location": {
|
||||
"origin": "11, 12",
|
||||
"scale": "2km"
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"query": {
|
||||
"match": {
|
||||
"properties": "balcony"
|
||||
"functions": [
|
||||
{
|
||||
"gauss": {
|
||||
"price": {
|
||||
"origin": "0",
|
||||
"scale": "20"
|
||||
}
|
||||
}
|
||||
},
|
||||
"score_mode": "multiply"
|
||||
{
|
||||
"gauss": {
|
||||
"location": {
|
||||
"origin": "11, 12",
|
||||
"scale": "2km"
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"query": {
|
||||
"match": {
|
||||
"properties": "balcony"
|
||||
}
|
||||
},
|
||||
"score_mode": "multiply"
|
||||
}
|
||||
}
|
||||
}
|
||||
}'
|
||||
--------------------------------------------------
|
||||
// AUTOSENSE
|
||||
|
||||
Next, we show how the computed score looks like for each of the three
|
||||
possible decay functions.
|
||||
|
||||
[[gauss-decay]]
|
||||
===== Normal decay, keyword `gauss`
|
||||
|
||||
When choosing `gauss` as the decay function in the above example, the
|
||||
|
|
@ -467,6 +502,7 @@ of 0.56. "BnB Bellevue" and "Backback Nap" are both pretty close to the
|
|||
defined location but "BnB Bellevue" is cheaper, so it gets a multiplier
|
||||
of 0.86 whereas "Backpack Nap" gets a value of 0.66.
|
||||
|
||||
[[exp-decay]]
|
||||
===== Exponential decay, keyword `exp`
|
||||
|
||||
When choosing `exp` as the decay function in the above example, the
|
||||
|
|
@ -476,6 +512,7 @@ image::https://f.cloud.github.com/assets/4320215/768161/082975c0-e899-11e2-86f7-
|
|||
|
||||
image::https://f.cloud.github.com/assets/4320215/768162/0b606884-e899-11e2-907b-aefc77eefef6.png[width="700px"]
|
||||
|
||||
[[linear-decay]]
|
||||
===== Linear decay, keyword `linear`
|
||||
|
||||
When choosing `linear` as the decay function in the above example, the
|
||||
|
|
@ -487,8 +524,7 @@ image::https://f.cloud.github.com/assets/4320215/768165/19d8b1aa-e899-11e2-91bc-
|
|||
|
||||
==== Supported fields for decay functions
|
||||
|
||||
Only single valued numeric fields, including time and geo locations,
|
||||
are supported.
|
||||
Only numeric, date, and geo-point fields are supported.
|
||||
|
||||
==== What if a field is missing?
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue