Ranking - Query pipeline feature

This is for:

In this article

Syntax
Example

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.

Example

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

Note

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.

Syntax

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

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

`<expressions>`

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

`<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.

Example

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.

`<options>`

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.

Example

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`	Total ranking score impact
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