Use query ranking expressions

One of the most direct ways you can influence relevance in your search solution is by designing and using query ranking expressions (QREs).

By default, the index computes a unique ranking score for each query result item based on various standard factors such as term frequency-inverse document frequency (TFIDF), term adjacency, and modification date. A QRE lets you further increase (or reduce) the ranking score of a specific subset of query result items by a fixed amount.

You can easily design, maintain, and test QREs by creating ranking expression and featured result rules in a query pipeline. You can also enforce QREs directly in the code of your search interface, although you should only do this if necessary.

Use cases

  • Top a result for a specific query:

    You significantly increase the ranking score for a single item that you want to promote when the user submits a specific popular basic query expression (q). This would likely be a featured result rule in a query pipeline.

  • Promote new content related to a query:

    You slightly increase the ranking score for items containing the latest release notes of a product when the user submits the basic query expression what’s new.

  • Demote content intended for another audience:

    You slightly reduce the ranking score for administrator-oriented documentation when the user has identified themselves as a developer.

  • Demote legacy content:

    You significantly reduce the ranking score for every item related to a legacy product, unless that product is explicitly included as a term in the basic query expression.

Leading practices

Use QREs for the right reasons

QREs are especially useful when you need to enforce specific or temporary business rules which your Coveo Machine Learning (Coveo ML) models couldn’t otherwise deduce from natural user behavior.

By increasing or decreasing the ranking scores of certain query result items under specific circumstances, you can lead a significant number of users to the most contextually-relevant content. Your Coveo ML models will learn from these positive outcomes and, in time, you will be able to stop enforcing the QREs.


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 for each result item whose @brand field value is ACME when the query contains the terms monitor or screen.

Promoting ACME monitors

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

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

Make your QREs just specific enough

Each QRE should only apply under specific circumstances. Before creating a QRE that affects most or all queries, consider whether you can improve relevance in your index itself.

However, you should also avoid creating QREs that are too specific. If a QRE applies to an insignificant volume of queries (such as 1 or 2 per month), it won’t produce enough usage analytics data for your Coveo ML models to learn from.

Test your QREs

QREs can have unexpected side-effects.

When you add a new QRE rule in a query pipeline (such as a ranking expression or featured result rule), it’s a good idea to use A/B testing to confirm that it has the expected effect on relevance in your search solution. If so, you can go ahead and let it alter a more significant volume of queries.

You may also want to set up A/B testing before you remove an existing QRE rule from a query pipeline.

Keep as few QREs as possible

QRE interactions can be complex, so it’s difficult to maintain many QREs in a search solution.

After a QRE has affected the behavior of a significant number of users for a long enough time, your Coveo ML models will adapt their output accordingly. This will often render the original QRE obsolete. When a QRE is no longer useful, you should consider removing it.

What’s next?

The Leverage Coveo Machine Learning article explains how to take advantage of the Coveo ML Query Suggestion (QS) and Automatic Relevance Tuning (ART) features.