Use query ranking expressions

This is for:

Developer System Administrator

One of the most direct ways you can influence relevance in your search solution is by designing and using query ranking expressions (QREs). With a QRE, you can further increase or reduce the ranking score of a specific subset of query result items by a fixed amount, after the standard ranking process has determined a result’s score.

You can create, manage, and test QREs by creating ranking expression 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.

What query ranking expressions are

By default, the index computes a unique ranking score for each query result item based on various standard ranking factors such as term frequency-inverse document frequency (TFIDF), term adjacency, and modification date.

A query ranking expression (QRE) is a rule that adds a fixed positive or negative value to the ranking score of items that match specific conditions. It targets a precise subset of results under precise conditions you define. You can use a QRE to enforce business rules before the models have enough data to act on their own.

Example

When you enforce a QRE directly in the code of your search interface, it takes the form of a $qre query extension in the advanced query (aq). For example, to boost every item whose @category field value is surf:

$qre(expression: @category=="surf", modifier: '50')

A modifier of 50 adds 500 to the ranking score of matching items, because the modifier value is correlated to the ranking score by a 1 to 10 ratio.

How QREs fit in the system

When you add a QRE, it takes effect immediately, making it well suited for enforcing business rules or addressing temporary relevance gaps while your search solution evolves.

QREs work alongside Coveo ML models. While the models learn from user behavior over time, you can use QREs to make targeted adjustments as needed. As user behavior changes and the models improve, you can review existing QREs to determine whether they’re still needed.

For the full execution order of all query pipeline features, see Order of execution of query pipeline features.

When to use QREs

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

Common scenarios include:

  • Promoting new content related to a query

    Your product just shipped new release notes, but users querying what’s new aren’t finding them because the content is too recent for your Coveo ML models to have learned from yet.

  • Enforcing a business rule

    Users querying cancel account should see retention-focused content first—but that business priority isn’t something the models can infer from query behavior alone.

  • Demoting content intended for another audience

    A user has identified themselves as a developer, but administrator-oriented content keeps surfacing prominently in their results.

  • Demoting legacy content

    Results for a legacy product are cluttering searches that aren’t specifically about that product, making it harder for users to find current content.

Leading practices

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 data for your Coveo ML models to learn from.

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

Review QREs periodically

QREs often address immediate business or relevance needs. As user behavior changes over time and your search solution evolves, review existing QREs to determine whether they’re still necessary.

Test your QREs

QREs can have unexpected side-effects, so validate new rules in a dedicated test scenario before applying them to your live pipeline. Use A/B testing to confirm that a new rule has the expected effect on relevance before applying it to a significant volume of queries. Use the same approach when you’re considering removing an existing rule.

Keep as few QREs as possible

QRE interactions can become difficult to understand and maintain as the number of rules grows. Create QREs only when they solve a clear relevance problem, and periodically review existing rules to remove or update those that are no longer needed.

What’s next?