Ranking - Query Pipeline Feature

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

Typically, a statement expressing the ranking feature should only apply when a certain condition is fulfilled.

In general, you should ensure that this is the case by associating such a statement, and/or the query pipeline it is defined in, to a global condition.

In the Coveo Cloud administration console you can manage statements expressing the ranking feature from the Ranking Expressions tab (see Adding and Managing Query Pipeline Ranking Expressions).

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 QPL syntax to define a statement expressing the ranking feature:

Syntax:

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

Where:

  • <expressions> is a comma-separated list of query expressions whose result set items should have their ranking scores modified by the statement (e.g., `foo`, `@bar=="baz"`). When the statement is applied, a distinct query ranking expression (qre) will be performed for each of those query expressions (e.g., $qre(expression: foo modifier: <modifier>) / $qre(expression: @bar=="baz" modifier: <modifier>).
  • <modifier> is 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> (e.g., 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.

  • <options> is 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 (e.g., `@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 is older than a year, and of each item that is marked as obsolete, by 100.
# Do not 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 previously created.

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