Adding and Managing Query Pipeline Ranking Expressions

A Coveo-powered search interface typically sorts query results by relevance. This means that items with high ranking scores normally appear on top of the result list.

When you have the required privileges, you can set ranking expressions rules in the Ranking Expressions tab1 of a query pipeline configuration to exercise direct control over item ranking scores.

1: In Coveo organizations that have gone through the query pipeline migration process, you must manage ranking expressions rules using the “Result Ranking” tab.

You want to promote ACME monitors in a Coveo-powered commerce portal.

In the portal’s query pipeline, you define a ranking expression rule that adds a positive modifier to the ranking score of each result item whose @brand field value is ACME when the query contains monitor or screen.

Example: Promote ACME monitors QRE

An end user accesses the commerce portal and submits the following query: globex computer screen.

Even though the end user is apparently looking for monitors of the Globex brand, your ranking expression rule is now likely to make ACME monitors appear higher in the result list.

Common Use Cases

Among other things, you can use ranking expression rules to:

Increase the ranking scores of items containing the most recent release notes when the end user submits a query containing release notes or what's new.

Example: a ranking expression rule promoting recent release notes

Enforce a Business Rule

Increase the ranking scores of items aimed at customer retention when the end user submits a query containing cancel account.

Example: a ranking expression rule promoting customer retention content

Demote Content Intended for Another Audience

Reduce the ranking scores of developer-oriented items when the end user has identified themselves as an administrator.

Example: a ranking expression rule demoting developer-oriented content

Demote Legacy Content

Reduce the ranking scores of all items related to a legacy product, unless the query contains that product name.

Example: a ranking expression rule demoting content related to a legacy product

Leading Practices

Consider the following leading practices when leveraging ranking expression rules:

Use Ranking Expression Rules for Legitimate Reasons

Ranking expression rules are especially useful when you need to enforce specific or temporary business rules which Coveo Machine Learning (Coveo ML) could otherwise hardly deduce from natural end-user behavior. By forcibly increasing or decreasing the ranking scores of certain query result items under certain circumstances, your goal should be to lead a significant number of end users to the most contextually relevant content, so that your Coveo ML models can eventually learn from those positive outcomes.

Use Ranking Expression Rules Sparingly

Maintaining a large number of ranking expression rules in a solution can prove highly complex. When a rule is no longer useful, consider removing it. After a while, if a rule has actually been affecting the behavior of a significant number of end users, your Coveo ML models will typically adapt their output accordingly, often rendering the original rule obsolete.

Make Your Ranking Expression Rules Just Specific Enough

Normally, you should apply a condition to each ranking expression rule. Instead of creating rules that affect most, or all queries originating from a search interface, consider whether you can apply indexing techniques to improve relevance directly in your index. Also avoid creating rules that are too specific; if a rule merely applies to an insignificant volume of queries (e.g., one or two queries per month), it will likely not produce enough compelling usage analytics data for your Coveo ML models to learn anything meaningful.

Test Your Ranking Expression Rules

Ranking expression rules can have unexpected side-effects. When you add a new rule in a query pipeline, it’s often a good idea to use A/B testing to validate whether this rule is affecting relevance as expected in your solution before allowing it to alter a significant volume of queries. You may also want to set-up an A/B test before definitively removing an existing rule from a query pipeline.

Adding a Rule

To add a ranking expression rule in a query pipeline

Image: Add a Ranking Expression Rule panel

  1. Access the “Ranking Expressions” tab of the desired query pipeline.

  2. In the upper-right corner, click Add Rule, and then select Ranking expressions rule.1

  3. On the Add a Ranking Expression Rule subpage that appears:

    1. In the Matching expressions inputs , enter the desired expressions.

    2. In the Modifier section, click and drag the slider to the desired modifier value.

    3. On the right-hand side, under Condition, you can optionally select a query pipeline condition in the drop-down menu or create a new one.

    4. Under User note, optionally enter information that will help you and your colleagues to manage the rules in the future.

    5. Click Add Rule.

The new ranking expression rule is effective immediately.

*: (Advanced) To define the rule using the appropriate QPL syntax, click Action-Menu, and then select Add rule with code.

Managing Existing Rules

See Managing Query Pipeline Rules From Tabs.


QPL Syntax

When creating a ranking expression rule with code or editing the code of an existing ranking expression rule, use the following query pipeline language (QPL) syntax:

boost <Expressions> by <Modifier> [with <Options>]

  • Increase the ranking score of each item whose title contains Coveo by 100.

    boost `@title/="^.*Coveo.*$"` by 10
  • 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



The Coveo Cloud query syntax expressions whose result items should have their ranking scores modified by the rule.

When the rule applies, a distinct query ranking expression (QRE) is generated for each of those expressions.

Expected type (QPL): list of query expressions

  • @brand==ACME

  • @audience==$context.userRole

When a rule contains an expression referencing a QPL object (e.g., @audience==$context.userRole), associate that rule with a query pipeline condition validating that the QPL object is populated with some value (e.g., when $context.userRole isPopulated). Otherwise, you risk modifying the ranking scores of unexpected items, as non-populated QPL objects are evaluated to the NOT operator.


A value indicating how much to boost or lower the ranking score of an item each time it appears in the result set of one of the rule’s expressions.

The modifier value is correlated to the ranking score of an item by a one to ten ratio (e.g., a modifier of 100 boosts the ranking score of each affected item by 1000). Setting the modifier to 0 renders the rule ineffective.

In the Coveo Cloud Administration Console, the minimum/maximum modifier value is +/- 1000 (in QPL, it’s +/- 1000000).

Expected type (QPL): primitive (integer)

  • Avoid using modifiers greater than 100 or lower than -100, unless you want to completely override the index ranking scores.

  • While the Modifier option lets you manually increase or decrease item’s ranking scores by 1,000 units, we recommend that you gradually adjust that score to efficiently evaluate the effect of your rule on your search results.

    As a rule of thumb, you should start by applying a modifier of 20 to 25 units, and then test your rule. If you’re not satisfied with the results, we suggest that you update the modifier in increments of 5 to 10 units before testing the rule again.

Options (QPL Only)

A hash in which each key must be a valid query ranking expression option, and each value must be of the expected type.

isConstant (Boolean)

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

Set this option to false when some, or all of the rule’s expressions are based on end-user input (e.g., @foo=$splitValues(text: $query, separator: '\s')) or contain nested queries.

Default: true

applyToEveryResults (Boolean)

Whether to apply the modifier to each item in the result set of each of the rule’s expressions, regardless of current ranking scores.

When this option is set to false, the modifier only applies to items whose current ranking score is considered high enough by the index.

Default: true

Order of Execution

The following diagram highlights the position of ranking expression rules in the overall order of execution of query pipeline features.

Apply ranking expression rules

Required Privileges

By default, members of the Administrators and Relevance Managers built-in groups can view and edit elements of the Query Pipelines page.

The following table indicates the required privileges to view or edit elements of the Query Pipelines page, and associated panels and subpages (see Privilege Management and Privilege Reference).

Action Service - Domain Required access level
View ranking expression rules

Search - Query pipelines

Edit ranking expression rules

Search - Query pipelines

Recommended Articles