Search API boosts

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.

« Search API Search API facets »