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 QRF 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 QRF. You can specify an array of QRF in a query using the rankingFunctions top-level query parameter.

Important

Ranking functions operate with floating-point precision rather than integers. As a result, calculations may introduce minor inaccuracies due to the inherent limitations of floating-point arithmetic.

Using ranking functions with dates or other data requiring high precision isn’t recommended, unless some imprecision is acceptable for your use case. For scenarios in which precision is critical, use query ranking expressions (QREs) instead.

Example

You want to increase the ranking score of restaurant items by an amount varying from 0 to 500, depending on their proximity to the user’s 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",
      ...
    },
    ...
  ],
  ...
}
Note

Suppose that the values returned by the -sqrt(dist(...)) function for a query are in the range [-1000, 0].

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 the rankingFunctions reference documentation.