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.

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 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)

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