Using Query Ranking Expressions

Coveo Relevance Cloud Developer System Administrator Product Documentation
In this article

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 (see Index Ranking Phases). A QRE lets you further increase (or reduce) the ranking score of a specific subset of query result items by a fixed amount (see About Search Result Ranking).

You can easily design, maintain, and test QREs by creating ranking expression and featured result rules in a query pipeline (see Manage Ranking Expression Rules and Manage Featured Result Rules). You can also enforce QREs directly in the code of your search interface, although you should only use this approach when truly necessary (see Add Query Ranking Expressions at Query Time).

Examples

Among other things, you could use QREs to:

  • Top a result for a specific query.

    E.g., significantly increase the ranking score of a single item you want to promote when the end 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.

    E.g., slightly increase the ranking score of items containing the latest release notes of a product when the end user submits the what’s new basic query expression while the tab corresponding to this product is selected in the search interface.

  • Demote content intended for another audience.

    E.g., slightly reduce the ranking score of administrator-oriented documentation when the end user has identified themselves as a developer.

  • Demote legacy content.

    E.g., significantly reduce the ranking score of all items related to a legacy product, unless that product is explicitly included as a basic query expression term.

Tip
Leading practice

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

    For example, 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.

  • Make your QREs just specific enough.

    Normally, a given 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. On the other hand, you should also avoid creating QREs that are too specific; if a QRE merely applies to an insignificant volume of queries (e.g., 1 or 2 queries per month), it will likely not produce enough compelling usage analytics (UA) data for your Coveo ML models to learn anything meaningful.

  • Test your QREs.

    QREs can have unexpected side-effects. When you add a new QRE rule in a query pipeline (i.e., a ranking expression or featured result rule), it’s often a good idea to use A/B testing to validate whether this rule is affecting relevance as expected in your search solution before allowing it to alter a significant volume of queries (see Manage A/B Tests). You may also want to set up an A/B test before definitively removing an existing QRE rule from a query pipeline.

  • Keep as few QREs as possible.

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

What’s Next?

The next article in this section explains how you can take advantage of the Coveo ML Query Suggestions (QS) and Automatic Relevance Tuning (ART) features (see Leveraging Coveo Machine Learning).