Ranking functions

This is for:

Developer
In this article

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.

Example

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
    }
  ]
}
Tip

200 OK response body (excerpt)

{
  ...
  "results": [
    {
      ...
      "score": 1642,
      "raw": {
        ...
        "latitude": -121.7890394,
        "longitude": 47.4951689
        ...
      },
      ...
      "title": "Double R Diner",
      ...
    },
    ...
  ],
  ...
}
Note

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 of 0 (0% of 500).

  • -750 has ranking score boost of 125 (25% of 500)

  • -500 has ranking score boost of 250 (50% of 500).

  • -250 has a ranking score boost of 375 (75% of 500).

  • 0 has a ranking score boost of 500 (100% of 500)

Reference

See rankingFunctions reference documentation.