The structure of the function query is quite simple and looks as follows:

{
 "query" : {
  "function_score" : {
   "query" : { ... },
   "functions" : [
     {
       "filter" : { ... },
       "FUNCTION" : { ... }
     }
   ],
   "boost_mode" : " ... ",
   "score_mode" : " ... ",
   "max_boost" : " ... ",
   "min_score" : " ... ",
   "boost" : " ... "
  }
 }
}

In general, the function score query can use a query, one of several functions, and additional parameters. Each function can have a filter defined to filter the results on which it will be applied. If no filter is given for a function, it will be applied to all the documents.

The logic behind the function score query is quite simple. First of all, the functions are matched against the documents and the score is calculated based on score_mode. After that, the query score for the document is combined with the score calculated for the functions and combined together on the basis of boost_mode.

Let's now discuss the parameters:

There is one thing to remember – we can limit the maximum calculated score value by using the max_boost parameter in the function score query. By default, that parameter is set to Float.MAX_VALUE, which means the maximum float value.

The boost parameter allows us to set a query wide boost for the documents.

Of course, there is one thing we should remember – the score calculated doesn't affect which documents matched the query. Because of that, the min_score property has been introduced. It allows us to define the minimum score of the documents. Documents that have a score lower than the min_score property will be excluded from the results.

What we haven't talked about yet are the function scores that we can include in the functions section of our query. The currently available functions are:

The weight factor function allows us to multiply the score of the document by a given value. The value of the weight parameter is not normalized and is taken as is. An example using the weight function, where we multiply the score of the document by 20, looks as follows:

curl -XGET 'localhost:9200/library/_search?pretty' -d '{
 "query" : {
  "function_score" : {
   "query" : {
    "term" : {
     "available" : true
    }
   },
   "functions" : [
    { "weight" : 20 }
   ]
  }
 }
}'

The field_value_factor function allows us to influence the score of the document by using a value of the field in that document. For example, to multiply the score of the document by the value of the year field, we run the following query:

curl -XGET 'localhost:9200/library/_search?pretty' -d '{
 "query" : {
  "function_score" : {
   "query" : {
    "term" : {
     "available" : true
    }
   },
   "functions" : [
    { 
     "field_value_factor" : {
      "field" : "year",
      "missing" : 1
     } 
    }
   ]
  }
 }
}'

In addition to choosing the field whose value should be used, we can also control the behavior of the field value factor function by using the following properties:

The script_score function allows us to use a script to calculate the score that will be used as the score returned by a function (and thus will fall into behavior defined by the boost_mode parameter). An example of script_score usage is as follows (for the following example to work, inline scripting needs to be allowed, which means adding the script.inline property and setting it to on in elasticsearch.yml):

curl -XGET 'localhost:9200/library/_search?pretty' -d '{
 "query" : {
  "function_score" : {
   "query" : {
    "term" : {
     "available" : true
    }
   },
   "functions" : [
    {
     "script_score" : {
      "script" : {
     "inline" : "_score * _source.copies * parameter1",
       "params" : {
        "parameter1" : 12
       }
      }
     }
    }
   ]
  }
 }
}'

By using the random_score function, we can generate a pseudo random score, by specifying a seed. In order to simulate randomness, we should specify a new seed every time. The random number will be generated by using the _uid field and the provided seed. If a seed is not provided, the current timestamp will be used. An example of using this is as follows:

curl -XGET 'localhost:9200/library/_search?pretty' -d '{
 "query" : {
  "function_score" : {
   "query" : {
    "term" : {
     "available" : true
    }
   },
   "functions" : [
    {
     "random_score" : {
      "seed" : 12345
     }
    }
   ]
  }
 }
}'

In addition to the earlier mentioned scoring functions, Elasticsearch exposes additional ones, called the decay functions. The difference from the previously described functions is that the score given by those functions lowers with distance. The distance is calculated on the basis of a single valued numeric field (such as a date, a geographical point, or a standard numeric field). The simplest example that comes to mind is boosting documents on the basis of distance from a given point or boosting on the basis of document date.

For example, let's assume that we have a point field that stores the location and we want our document's score to be affected by the distance from a point where the user stands (for example, our user sends a query from a mobile device). Assuming the user is at 52, 21, we could send the following query:

{
 "query" : {
  "function_score" : {
   "query" : {
    "term" : {
     "available" : true
    }
   },
   "functions" : [
    {
     "linear" : {
      "point" : {
       "origin" : "52, 21",
       "scale" : "1km",
       "offset" : 0,
       "decay" : 0.2
      }
     }
    }
   ]
  }
 }
}

In the preceding example, the linear is the name of the decay function. The value will decay linearly when using it. The other possible values are gauss and exp. We've chosen the linear decay function because of the fact that it sets the score to 0 when the field value exceeds the given origin value twice. This is useful when you want to lower the value of the documents that are too far away.

Now let's discuss the rest of the query structure. The point is the name of the field we want to use for score calculation. If the document doesn't have a value in the defined field, it will be given a value of 1 for the time of calculation.

In addition to that, we've provided additional parameters. The origin and scale are required. The origin parameter is the central point from which the calculation will be done and the scale is the rate of decay. By default, the offset is set to 0. If defined, the decay function will only compute a score for the documents with value greater than the value of this parameter. The decay parameter tells Elasticsearch how much the score should be lowered and is set to 0.5 by default. In our case, we've said that, at the distance of 1 kilometer, the score should be reduced by 20% (0.2).