Search API boosts
editSearch API boosts
editWe have a Relevance Tuning guide that gets deep into boosts.
Boosts affect the score of the entire document.
Provide a field to boost, then increase document relevance based on values.
Type | Value Boosts | Functional Boosts | Proximity Boosts | Recency Boosts |
---|---|---|---|---|
|
Yes |
No |
No |
No |
|
Yes |
Yes |
Yes |
No |
|
Yes |
No |
No |
Yes |
|
No |
No |
Yes |
No |
Value Boosts
editA Value Boost will boost the score of a document based on a direct value match.
Available on text, number, and date fields.
A document’s overall score will only be boosted once.
-
type
(required) - Type of boost. For a Value Boost, this should be value.
-
value
(required) - The value to exact match on. Use an array to match on multiple values.
-
operation
(optional) - The arithmetic operation used to combine the original document score with your boost value. Can be add or multiply. Defaults to add.
-
factor
(optional) - Factor to alter the impact of a boost on the score of a document. Must be between 0 and 10. Defaults to 1.0. A negative factor or fractional factor will not deboost a result.
Example - Applying a multiplicative value
boost to parks that have world_heritage_site
as "true". Increases relevance.
curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "query": "heritage site", "boosts": { "world_heritage_site": [ { "type": "value", "value": "true", "operation": "multiply", "factor": 10 } ] } }'
Functional Boosts
editA functional
boost will apply a function to the overall document score.
Only available on number fields.
-
type
(required) - Type of boost. For a Functional Boost, this should be functional.
-
function
(required) - Type of function to calculate the boost value. Can be linear, exponential, or logarithmic.
-
operation
(optional) - The arithmetic operation used to combine the original document score with your boost value. Can be add or multiply. Defaults to add.
-
factor
(optional) - Factor to alter the impact of a boost on the score of a document. Must be between 0 and 10. Defaults to 1.0. A negative factor or fractional factor will not deboost a result.
Example - Applying a multiplicative functional
boost on all park document scores based on their number of visitors
. Increases relevance.
curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "boosts": { "visitors": { "type": "functional", "function": "logarithmic", "operation": "multiply", "factor": 2 } }, "query": "popular parks" }'
Proximity Boosts
editBoost on the difference of a document value and a given value from the center
parameter.
Available on number and geolocation fields.
For date fields see Recency Boosts.
-
type
(required) - Type of boost. For a Proximity Boost, this should be proximity.
-
center
(required) -
The mode of the distribution, specified as a latitude-longitude pair. See Geolocation fields.
-
function
(required) - Type of function to calculate the boost value. Can be linear, exponential, or gaussian.
-
factor
(optional) - Factor to alter the impact of a boost on the score of a document. Must be between 0 and 10. Defaults to 1.0. A negative factor or fractional factor will not deboost a result.
Example - Applying a proximity
boost based on park location
relative to the Elastic office in San Francisco. Increases relevance based on proximity.
curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "boosts": { "location": { "type": "proximity", "function": "linear", "center": "25.32, -80.93", "factor": 8 } }, "query": "old growth" }'
Recency Boosts
editA Proximity Boost, but with a timeframe as the center instead of a coordinate. Use Recency Boosts to boost newer documents.
A Recency Boost relies on a decay function using a hard-coded scale of 1 day. The boost decreases very quickly; it is not possible to significantly boost a document that is older than a couple days from the center
date.
Only applies to date fields.
-
type
(required) - Type of boost. For a Recency Boost, this should be proximity.
-
center
(required) - Provide a time-frame. Consider using now to establish recency from the present time.
-
function
(required) - Type of function to calculate the boost value. Can be linear, exponential, or gaussian. All functions decay rapidly towards 0 after about 2 days because the decay scale is 1 day.
-
factor
(optional) - Alter the impact of a boost on the score of a document. Must be between 0 and 10. Defaults to 1.0. A negative factor or fractional factor will not deboost a result. The factor parameter multiplies the value of the boost but does not significantly affect the decay function scale.
Example - Using the type proximity
with a center of now
on the date_established
field to apply a Recency Boost. We increase the relevance of the newest parks.
curl -X GET '<ENTERPRISE_SEARCH_BASE_URL>/api/as/v1/engines/national-parks-demo/search' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer search-soaewu2ye6uc45dr8mcd54v8' \ -d '{ "boosts": { "date_established": { "type": "proximity", "function": "linear", "center": "now", "factor": 8 } }, "query": "old growth" }'
Errors
edit
|
If the boosted field is not in the schema. If the boost JSON object is malformed, missing required arguments, or has invalid values. If a Value Boost is not on a field type that is not text, number, or date. If a Functional Boost is on a field type that is not number. If a Proximity Boost is on a field type that is not number, date, or geolocation. |