Search API boosts

edit

Search API boosts

edit

We 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

text

Yes

No

No

No

number

Yes

Yes

Yes

No

date

Yes

No

No

Yes

geolocation

No

No

Yes

No

Value Boosts

edit

A 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 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/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

edit

A 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 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/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

edit

Boost 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 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/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

edit

A 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 'https://[instance id].ent-search.[region].[provider].cloud.es.io:443/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

boosts

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.