---
title: Manage ranking expression rules
slug: '3375'
canonical_url: https://docs.coveo.com/en/3375/
collection: tune-relevance
source_format: adoc
---
# Manage ranking expression rules
A Coveo-powered [search interface](https://docs.coveo.com/en/2741/) typically sorts [query](https://docs.coveo.com/en/231/) results by relevance.
This means that [items](https://docs.coveo.com/en/210/) with high ranking scores normally appear at the top of the results list.

With the [required privileges](https://docs.coveo.com/en/3375#required-privileges), you can define [query pipeline](https://docs.coveo.com/en/180/) [ranking expression](https://docs.coveo.com/en/1472/) [rules](https://docs.coveo.com/en/236/) to help exercise direct control over item ranking scores.
This can be done on the **Result Ranking** tab of the query pipeline page.

**Example**

Your company, _Barca Sports_, has a popular blog that covers various sports throughout the year.
With surf season around the corner, the marketing team has added new articles dedicated to choosing the right gear and apparel for surfing.
To ensure that these articles appear at the top of the search results when queries contain the word `surf`, so you create a ranking expression rule that boosts the score of items containing the word `surf` by `50`.

![Example: a ranking expression rule boosting the score of items](https://docs.coveo.com/en/assets/images/tune-relevance/ranking-expression-example.gif)

## Prerequisites

Before creating a rule, make sure that you have the following:

* Access to a search page

You need access to a Coveo-powered [search interface](https://docs.coveo.com/en/2741/) to be able to test the [rule](https://docs.coveo.com/en/236/) that you create.

* An existing query pipeline

The queries from the search page must travel through a specific [query pipeline](https://docs.coveo.com/en/180/).

* Required privileges

You need specific [privileges to be able to add and edit rules in a query pipeline](#required-privileges).

Once you meet these requirements, you can create a rule on the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page.
To test the rule, [use the A/B test feature](https://docs.coveo.com/en/3255/) to compare the results of the rule with the results of the original pipeline.

## Common use cases

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

* Promote new content related to a query.

For example, you 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 | Coveo](https://docs.coveo.com/en/assets/images/tune-relevance/promote-recent-release-notes.png)

* Enforce a business rule.

For example, you 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 | Coveo](https://docs.coveo.com/en/assets/images/tune-relevance/promote-customer-retention-items.png)

* Demote content intended for another audience.

For example, you 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](https://docs.coveo.com/en/assets/images/tune-relevance/demote-developer-content.png)

* Demote legacy content.

For example, you 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](https://docs.coveo.com/en/assets/images/tune-relevance/demote-legacy-product-content.png)

## Create or edit ranking expression rules

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline in which you want to add or edit a rule, and then click **Edit components** in the Action bar.

. On the page that opens, select the **Result Ranking** tab, and then do one of the following:

* To add a rule

.. Click **Add rule**.

.. In the **Add Ranking Rule** modal that opens, select **Ranking expression**.

* To edit a rule

.. Click the rule you want to edit, and then click **Edit** in the Action bar.

. In the [**Content that matches**](#content-that-matches-section) section, depending on the mode, use either the dropdown menus or the input to enter or modify the desired filter expressions.

. Under **Will have its score changed by**, move the slider to lower or boost the score of items that meet the specified filter expressions.
The default score is `0` (meaning that the item score is neither lowered nor boosted).

Avoid modifiers greater than `100` or lower than `-100`, unless you want to completely override the index ranking scores.
To make a specific item appear at the top of the search results, use [featured result rules](https://docs.coveo.com/en/3376/) instead.

> **Important**
>
> The selected score value affects the final [search result relevance score](https://docs.coveo.com/en/1624#relevance-score) by a 1 to 10 ratio.
> 
> For example, if you select to boost the score of items that meet the specified filter expressions by a score of `100`, this expression adds `1,000` to the final search result ranking score of matching items.

. Under **If the following conditions are met**, you can optionally associate your ranking expression rule to a [group of rules](https://docs.coveo.com/en/3283/) or assign a [query pipeline condition](https://docs.coveo.com/en/2793/):

** To associate your ranking expression rule to a group of rules, under **Use a group condition**, type or select the desired group from the dropdown menu, or [create a new one](https://docs.coveo.com/en/3283#add-a-group).

**Example**

Your Coveo-powered commerce portal at _Barca Sports_ includes the `Commerce` query pipeline.
This pipeline has both featured result and ranking expression rules for specific sport-related searches, such as "cycling equipment" or "skiing gear."

These rules help promote different items to best suit the shopper's _Barca Sports_ profile.
For instance, they promote starter cycling gear to beginner cyclists and advanced skiing equipment to self-described intermediate skiers.

Since you're promoting different products for different user profiles, you create two separate groups of query pipeline rules.
Each group's rules adjust the search results to align with the shopper's expertise in their sport of interest.

For more examples on creating groups of rules, see [Common use cases](https://docs.coveo.com/en/3283#common-use-cases).

** To assign a query pipeline condition to your ranking expression rule, under **Use an independent condition**, type or select the desired condition from the dropdown menu, or [create a new one](https://docs.coveo.com/en/1959#create-a-condition).

. Review your ranking expression rule on the **Preview** test search page.

Note that the customizations you made in the [search interface builder](https://docs.coveo.com/en/1656/) (or the [Interface Editor](https://docs.coveo.com/en/1852/), if applicable) don't apply in this preview.

> **Tip**
>
> You can move the slider under **Will have its score changed by** to see its effect on the ranking score in real time on the **Preview** test search page.

. Do one of the following:

* If you created a new rule, click **Add rule**.

** In the **Name your rule** input of the **Rule information** modal that opens, enter a name for your rule.

** In the **User note** input, optionally enter text with information that could help you and your colleagues manage the rule in the future.

* If you edited an existing rule, you have the option to rename or update the user note associated with your ranking expression rule:

** In the upper-left corner, click **Edit information**.

** In the **Name your rule** input of the **Rule information** modal that opens, review the name of your rule.

** In the **User note** input, optionally enter text with information that could help you and your colleagues manage the rule in the future.

** Click **Save**.

. Click **Save**.

The rule is effective immediately.

## Modify ranking expression JSON configuration

Editing a rule JSON configuration is especially useful when you want to implement a rule that doesn't fit with the parameters available in the Coveo Administration Console.

> **Note**
>
> For the complete parameter definitions, see [Update a result ranking rule](https://docs.coveo.com/en/13#operation/updateResultRankingRule).

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline for which you want to modify existing query pipeline rules, and then click **Edit components** in the Action bar.

. On the page that opens, select the **Result Ranking** tab.

. On the **Result Ranking** tab, click the rule you want to modify, and then click **Edit JSON** in the Action bar.

. On the **Edit a ranking expressions JSON Rule** subpage, make the desired modifications.

. Click **Save**.

## Duplicate ranking expression rules

When creating ranking expression rules in a query pipeline, you may want to create a new rule that's similarly configured to an existing one.
An efficient way to do this is to duplicate the existing rule and then modify it as needed.

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline for which you want to duplicate rules, and then click **Edit components** in the Action bar.

. Select the **Result Ranking** tab, and then select the rules you want to duplicate within the same pipeline.

. In the Action bar, click **Duplicate**.

The duplicated ranking expression rules appear at the bottom of the list in the pipeline component tab.

## Copy ranking expression rules to another pipeline

When you have multiple query pipelines that require similar rules, you can copy ranking expression rules from one pipeline to another.

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline from which you want to copy rules, and then click **Edit components** in the Action bar.

. Select the **Result Ranking** tab, and then select the rules you want to copy to another pipeline.

. In the **Action** bar, click **More**, and then click **Copy to...**.

. In the dialog that appears, select the target pipeline to which you want to copy the rules, and then click **Copy**.

Your copied rules will take effect immediately in the target pipeline.

## Delete ranking expression rules

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline that contains the rules you want to delete, and then click **Edit components** in the Action bar.

. Select the **Result Ranking** tab, and then select the rules you want to delete.

. In the Action bar, click **More**, and then click **Delete**.

. Click **Delete** to confirm.

Your deleted rules will stop being effective immediately in the target pipeline.

> **Tip**
>
> * To avoid undesired search behaviors, delete unused query pipeline rules, as they can impact search relevance.
> 
> * Consider using the [Groups & Campaigns feature](https://docs.coveo.com/en/3283/) to make query pipeline rules only apply for a specific time period.

## 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 enforcing specific or temporary business rules which [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) 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](https://docs.coveo.com/en/1012/) can eventually learn from those positive outcomes.

* Use ranking expression rules sparingly.

Maintaining many ranking expression rules in a solution can prove highly complex.
In addition, ranking expression rules require a significant amount of processing power, so using many of them can slow down the [search response time](https://docs.coveo.com/en/1948/).

> **Leading practice**
>
> If one or more of your ranking expression rules are only relevant for a specific period of time, you should consider including them in a [campaign group](https://docs.coveo.com/en/3283/).
> This feature lets you specify a period of time for which the rules must be effective.
> When the specified end date is reached, targeted rules are automatically deactivated.

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](#create-or-edit-ranking-expression-rules) to a 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](https://docs.coveo.com/en/2721/) to improve relevance directly in your [index](https://docs.coveo.com/en/204/).
Also avoid creating rules that are too specific.
If a rule applies to only one or two queries per month, it will likely not produce enough compelling [data](https://docs.coveo.com/en/259/) 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](https://docs.coveo.com/en/3255/) 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.

## "Content that matches" section

When creating a rule, under the **Content that matches** section, you must define filter expressions for which matching result items should have their ranking scores modified by the rule.

You can define filter expressions using either the ["Basic mode"](#basic-mode) or ["Advanced mode."](#advanced-mode)

## Basic mode

To define filter expressions using the **Basic mode**:

. [[step1]]In the **Select field** dropdown menu, use the **Filter** box to find and select the field that must be targeted by the filter expression.

. [[step2]]In the **Select a comparator** dropdown menu, select one of the [available comparators](#operators).

. If applicable, in the **Select a field value** dropdown menu, enter or select the values that must be filtered according to the field selected in [step 1](#step1).

. (Optional) Click **Add** to add another filter expression to the rule.
Note that when adding multiple filter expressions to a rule, new filter expressions are appended to the initial expression using the `and` logic, meaning that only content matching all filter expressions will be affected by the rule.

**Example**

Only items whose `author` is `Coveo` and which were created or updated in the last month will be affected by the rule.

![Coveo Platform | Content that matches section](https://docs.coveo.com/en/assets/images/tune-relevance/query-pipeline-rule-content-that-matches.png)

## Advanced mode

To define filter expressions using the **Advanced mode**, enter a [query expression](https://docs.coveo.com/en/2830/) using the [query syntax](https://docs.coveo.com/en/1552/).

**Example**

Only items whose `author` is `Coveo` and which were created or updated in the last month will be affected by the rule.

![Coveo Platform | Content that matches section - Advanced](https://docs.coveo.com/en/assets/images/tune-relevance/query-pipeline-rule-content-that-matches-advanced.png)

:leveloffset!:

## Operators

## Contains

For the ranking expressions to modify the ranking score of the search results of an end user, the expression selected or entered in the **Select a field value** input must be part of the end user query.

## Does not contain

For the ranking expressions to modify the ranking score of the search results of an end user, the expression selected or entered in the **Select a field value** input must not be part of the end user query.

## Is

For the ranking expressions to modify the ranking score of the search results of an end user, the expression selected or entered in the **Select a field value** input must be the same as the end user query.

## Is defined

For the ranking expressions to modify the ranking score of the search results of an end user, the field selected in the **Select field** dropdown menu must be defined in the end user query.

## Is not

For the ranking expressions to modify the ranking score of the search results of an end user, the expression selected or entered in the **Select a field value** input must not be the same as the end user query.

## Is not defined

For the ranking expressions to modify the ranking score of the search results of an end user, the field selected in the **Select field** dropdown menu must not be defined in the end user query.

## Matches

(For advanced users) For the ranking expressions to modify the ranking score of the search results of an end user, their query must match the regular expression (regex) entered in the filter expression.

## Since

For the ranking expressions to modify the ranking score of the search results of an end user, the date field selected in the **Select field** dropdown menu must be more recent than the date selected or entered in the **Select a field value** input.

:leveloffset!:

## Order of execution

The following diagram illustrates the [order of execution of query pipeline features](https://docs.coveo.com/en/1376/):


![Diagram showing order of execution | Coveo](https://docs.coveo.com/en/assets/images/tune-relevance/order-of-execution-query-pipeline-features.png)

## Required privileges

The following table indicates the [privileges](https://docs.coveo.com/en/1791#required-privileges) required to view or edit ranking expressions.
Learn more about the [Privilege reference](https://docs.coveo.com/en/1707/) or how to [manage privileges](https://docs.coveo.com/en/3151/).

[cols="3",options="header"]
|===
|Action
|Service - Domain
|Required access level

|View ranking expressions rules
|Organization - Organization  
Search - Query pipelines
|View

.3+|Edit ranking expressions rules using the [**Basic mode**](https://docs.coveo.com/en/3375#basic-mode)
|Organization - Organization  
Content - Fields
|View

|Search - Query pipelines
|Edit

|Search - Execute queries
|Allowed

.3+|Edit ranking expressions rules using the [**Advanced mode**](https://docs.coveo.com/en/3375#advanced-mode)
|Organization - Organization
|View

|Search - Query pipelines
|Edit

|Search - Execute queries
|Allowed
|===