Ranking - Query pipeline feature

In this article

A query pipeline statement expressing the ranking feature generates query ranking expressions (QRE) to increase or decrease the ranking scores of items appearing in certain query result sets by a specific amount.

Leading practice

Typically, a ranking statement should only apply when a condition is satisfied.

This means you should associate such a statement, and/or the query pipeline it’s defined in, to a condition.

This is particularly important when a ranking statement references a QPL object. In such a case, you should associate the statement with a condition that validates that the QPL object is populated. Otherwise, you risk inadvertently altering the ranking scores of undesired items, as a non-populated QPL object is evaluated to the NOT operator.


Consider the following ranking statement.

boost `@audience==$context.userRole` by 100

For a given query, if the $context.userRole key isn’t populated, the resulting QRE is equivalent to:

$qre(expression: NOT @audience, modifier: '100')

Meaning that all items whose @audience field isn’t populated have their ranking score increased by 1,000 points.

To prevent this, the statement should only apply when the $context.userRole key is populated, which can be done by associating it with the following condition:

when $context.userRole isPopulated

In the Coveo Administration Console you can manage statements expressing the ranking feature from the Ranking Expressions tab (see Manage ranking expression rules).

The following diagram shows the process of a query being sent to the Search API and the order of execution of query pipeline features.

Apply ranking statements


Use the following query pipeline language (QPL) QPL syntax to define a statement expressing the ranking feature:

boost <expressions> by <modifier> [with <options>]


A comma-separated list of query expressions whose result set items should have their ranking scores modified by the statement (for example, foo`, `@bar=="baz").

When the statement is applied, a distinct query ranking expression (QRE) will be performed for each of those query expressions (for example, $qre(expression: foo modifier: <modifier>) / $qre(expression: @bar=="baz" modifier: <modifier>)).


An integer indicating how much to increase or reduce the ranking score of an item when it appears in the result set of one of the <expressions> (for example, 50). Minimum value is -1000000. Maximum value is 1000000.


The <modifier> value is correlated to the ranking score of an item by a 1 to 10 ratio.


In the QPL definition of a statement expressing the ranking feature, setting the <modifier> to 100 means that when this statement is applied, the ranking score of an item will increase by 1000 each time that item appears in the result set of one of the <expressions>.

Typically, you should use a <modifier> value between -100 and 100, unless you want to completely override the index ranking scores.


A comma separated list of key-value pairs, where each key must be a valid query ranking expression option and each value must be a Boolean. The following table lists the available options:

Key Default value Description
isConstant true

Whether to treat the expression argument of each query ranking expression generated by the statement as a constant expression (and cache its results).

You should set this option to false when some, or all of the <expressions> are based on end-user input (for example, `@foo=$splitValues(text: $query, separator: '\s')`) or contain nested queries.
applyToEveryResults true Whether to apply the <modifier> to each item in each <expressions> result set, regardless of its current ranking score. When this option is set to false, the <modifier> will only apply to items whose current ranking score is considered high enough by the index.


You create a global condition with the following QPL definition:

Global condition:

when $originalQuery contains `machine learning`

In an empty query pipeline named Testing Ranking, you create two distinct statements, each expressing the ranking feature, with the following QPL definitions:

Statement 1:

# Increase the ranking score of each item whose title contains "Coveo" by 100.
boost `@title/="^.*Coveo.*$"` by 10

Statement 2:

# Reduce the ranking score of each item that's older than a year, and of each item that's marked as obsolete, by 100.
# Don't modify the ranking score of an item if its current ranking score is already considered too low by the index.
boost `@date<today-1y`, `@isobsolete=="true"` by -10 with applyToEveryResults: false

You associate each of those two statements with the global condition you created before.

A user performs a query against your index with the following payload:

Query payload:

  "pipeline": "Testing Ranking",
  "q": "machine learning features"

Since this query goes through the Testing Ranking query pipeline and satisfies the condition of each statement in that pipeline, those statements are applied. As a result, the following query ranking expressions are performed:

  • $qre(expression: @title/="^.*Coveo.*$", modifier: 10, isConstant: false, applyToEveryResults: true) (because of Statement 1)

  • $qre(expression: @date<today-1y, modifier: -10, isConstant: false, applyToEveryResults: false) (because of Statement 2)

  • $qre(expression: @isobsolete=="true", modifier: -10, isConstant: false, applyToEveryResults: false) (because of Statement 2)

The table below summarizes how the ranking score of an item appearing in the result set of that query will be affected by the statements in the Testing Ranking query pipeline, depending on which query expression/expressions this item matches (assuming that the current score of this item is high enough for the index to apply the query ranking expressions generated by Statement 2):

Item matches

Total ranking score impact

@title/="^.*Coveo.*$ @date<today-1y @isobsolete=true
No No No 0
No No Yes -100
No Yes No -100
No Yes Yes -200
Yes No No +100
Yes No Yes 0
Yes Yes No 0
Yes Yes Yes -100