Ranking functions
Ranking functions
A ranking function is a mathematical expression evaluated against each item returned by a query. The ranking function output for a given item generates a boost which is then added to the ranking score of that item.
This article describes the members of the structure that defines a single ranking function. You can specify an array of ranking functions in a query using the rankingFunctions
top-level query parameter.
You want to increase the ranking score of restaurant items by an amount varying from 0
to 500
, depending on how close they’re to the end-user location.
POST https://platform.cloud.coveo.com/rest/search/v2 HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
Payload
{
"aq": "documenttype==Restaurant",
"rankingFunctions": [
{
"expression": "-sqrt(dist(@longitude, @latitude, 47.4953481, -121.7885868))",
"normalizeWeight": true,
"modifier": 500
}
]
}
200 OK response body (excerpt)
{
...
"results": [
{
...
"score": 1642,
"raw": {
...
"latitude": -121.7890394,
"longitude": 47.4951689
...
},
...
"title": "Double R Diner",
...
},
...
],
...
}
Suppose that the values returned by the -sqrt(dist(...))
function for a query are in the range [-1000, 0]
.
Then, the result for a restaurant item that has a -sqrt(dist(...))
value of:
-
-1000
has a ranking score boost of0
(0% of 500). -
-750
has ranking score boost of125
(25% of 500) -
-500
has ranking score boost of250
(50% of 500). -
-250
has a ranking score boost of375
(75% of 500). -
0
has a ranking score boost of500
(100% of 500)
Ranking function parameters
This section provides reference documentation for the available ranking function parameters.
expression (string)
A mathematical expression to evaluate for each query result. The result of this expression for a given query result generates a boost which is then added to the ranking score of that query result.
Note: Query ranking function expressions support the ExprTk library syntax. However, the following statements are disabled:
-
if
/else
switch
while
repeat until
The following time constants are also available in query ranking functions:
-
NOW
: A value corresponding to the precise moment when the query reaches the index. -
YEAR
: A value corresponding to the duration of a year (i.e., 365.25 days). -
WEEK
: A value corresponding to the duration of a week. -
DAY
: A value corresponding to the duration of a day.
Tip: If your query ranking function expression references certain numeric fields, you should ensure that the Use cache for computed fields option is enabled for each of those fields in order to speed up evaluation (see Add or Edit Fields).
Example: -sqrt(dist(@longitude, @latitude, 46.8167, -71.2167))
modifier (integer [int64])
The maximum boost this query ranking function can add to the ranking score of any given query result.
This property only has a meaning if normalizeWeight
is set to true
.
Default: 600
normalizeWeight (boolean)
Whether to normalize the ranking score boosts resulting from the evaluation of this query ranking function using the standard index scale.
Unless you want to completely override the index ranking and use the results of this query ranking function directly to boost the ranking scores of query results, you should set this to true
.
Default: false