Many variables could influence the user’s choice of vacation home. Maybe she would like to be close to the center of town, but perhaps would be willing to settle for a place that is a bit farther from the center if the price is low enough. Perhaps the reverse is true: she would be willing to pay more for the best location.

If we were to add a filter that excluded any vacation homes farther than 1 kilometer from the center, or any vacation homes that cost more than £100 a night, we might exclude results that the user would consider to be a good compromise.

The function_score query gives us the ability to trade off one sliding scale (like location) against another sliding scale (like price), with a group of functions known as the decay functions.

The three decay functions—​called linear, exp, and gauss—operate on numeric fields, date fields, or lat/lon geo-points. All three take the same parameters:

The only difference between these three functions is the shape of the decay curve. The difference is most easily illustrated with a graph (see Figure 33, “Decay function curves”).

Figure 33. Decay function curves

The curves shown in Figure 33, “Decay function curves” all have their origin—the central point—​set to 40. The offset is 5, meaning that all values in the range 40 - 5 <= value <= 40 + 5 are treated as though they were at the origin—they all get the full score of 1.0.

Outside this range, the score starts to decay. The rate of decay is determined by the scale (which in this example is set to 5), and the decay (which is set to the default of 0.5). The result is that all three curves return a score of 0.5 at origin +/- (offset + scale), or at points 30 and 50.

The difference between linear, exp, and gauss is the shape of the curve at other points in the range:

Which curve you choose depends entirely on how quickly you want the _score to decay, the further a value is from the origin.

To return to our example: our user would prefer to rent a vacation home close to the center of London ({ "lat": 51.50, "lon": 0.12}) and to pay no more than £100 a night, but our user considers price to be more important than distance. We could write this query as follows:

GET /_search
{
  "query": {
    "function_score": {
      "functions": [
        {
          "gauss": {
            "location": { 
              "origin": { "lat": 51.5, "lon": 0.12 },
              "offset": "2km",
              "scale":  "3km"
            }
          }
        },
        {
          "gauss": {
            "price": { 
              "origin": "50", 
              "offset": "50",
              "scale":  "20"
            }
          },
          "weight": 2 
        }
      ]
    }
  }
}

The location clause is easy to understand: