IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

› ›

Search API boosts

edit

IMPORTANT: This documentation is no longer updated. Refer to Elastic's version policy and the latest documentation.

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
`text`	Yes	No	No
`number`	Yes	Yes	Yes
`date`	Yes	No	No
`geolocation`	No	No	Yes

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/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/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.

type (required): Type of boost. For a Proximity Boost, this should be proximity.
center (required): The mode of the distribution.
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/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"
}'

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 »