IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Search Facets »
Elastic Docs › ›API Reference

Boosts

edit

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 or decrease 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

Yes

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 -10 and 10. Defaults to 1.0.

Example - Applying a multiplicative value boost to parks that have world_heritage_site as "true". Increases relevance.

curl -X GET 'https://host-2376rb.api.swiftype.com/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
      }
    ]
  }
}'

Example - Applying negative, multiplicative value boost to parks that have world_heritage_site as "true". Decreases relevance.

curl -X GET 'https://host-2376rb.api.swiftype.com/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": -5
      }
    ]
  }
}'

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 -10 and 10. Defaults to 1.0.

Example - Applying a multiplicative functional boost on all park document scores based on their number of visitors. Increases relevance.

curl -X GET 'https://host-2376rb.api.swiftype.com/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"
}'

Example - Applying a negative, multiplicative functional boost on all park document scores based on their number of visitors. Decreases relevance.

curl -X GET 'https://host-2376rb.api.swiftype.com/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": -4
    }
  },
  "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.
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 -10 and 10. Defaults to 1.0.

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://host-2376rb.api.swiftype.com/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"
}'

Example - Applying a negative proximity boost based on park location relative to the Elastic office in San Francisco. Decreases relevance based on proximity.

curl -X GET 'https://host-2376rb.api.swiftype.com/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": -6
    }
  },
  "query": "old growth"
}'

Recency Boosts

edit

A Proximity Boost, but with a timeframe as the center instead of a coordinate.

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.
factor (optional)
Factor to alter the impact of a boost on the score of a document. Must be between -10 and 10. Defaults to 1.0.

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://host-2376rb.api.swiftype.com/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"
}'

Example - Applying Recency Boost by using the type proximity with a center of now on the date_established field. We decrease the relevance of the newest parks.

curl -X GET 'https://host-2376rb.api.swiftype.com/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": -4
    }
  },
  "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 Facets »