---
title: Manage ranking weight rules
slug: '3412'
canonical_url: https://docs.coveo.com/en/3412/
collection: tune-relevance
source_format: adoc
---
# Manage ranking weight rules
A Coveo [index](https://docs.coveo.com/en/204/) uses a number of [ranking factors](#ranking-factors) to evaluate the relevance score of each search result for a given [query](https://docs.coveo.com/en/231/).
When the [search interface](https://docs.coveo.com/en/2741/) sorting is set to **Relevance**, the search results are presented in descending relevance score order to present the most pertinent [items](https://docs.coveo.com/en/210/) at the top.

Members with the [required privileges](#required-privileges) can configure [query pipeline](https://docs.coveo.com/en/180/) ranking weight [rules](https://docs.coveo.com/en/236/) to fine-tune one or more of the [pre-tuned ranking factors](#ranking-factors) for a specific query pipeline.

**Example**

Your company, _Barca Sports_, maintains a large online catalog and sports blog.
As surf season approaches, a series of new blog posts about surf gear and tips are published.
When testing queries such as `surfboard` or `wetsuit`, you notice that older articles about surfing are ranking above the newly added posts.

To fix this, you create a ranking weight rule with the following adjustments:

* You increase the weight of [**Item last modification**](#item-last-modification) from 5 to 8 to favor recently updated content.

* You slightly boost [**Keyword in title**](#keyword-in-title) from 5 to 6 to reward items whose titles match the user query more closely.

These tuning adjustments make newer, more relevant surf posts appear higher in the results.

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

## Access the "Ranking Weights" subtab

To manage ranking weight rules, you must first access the **Ranking Weights** subtab in a query pipeline.

. 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 manage ranking weight rules, and then click **Edit components** in the Action bar.

. On the page that opens, select the **Advanced** tab.

. On the **Advanced** tab, on the left side of the page, select **Ranking Weights**.

## Add or edit ranking weight rules

. [Access the **Ranking Weights** subtab](#access-the-ranking-weights-subtab) in the query pipeline you want to manage, then do one of the following:

* To add a new rule, click **Add ranking weight rule**.

> **Notes**
>
> * If you're adding a ranking weight rule for the first time, you can click **Add rule with code** to define the rule using the appropriate [QPL syntax](#qpl-syntax).
> * If you're adding a ranking weight to a list of existing rules, you can click [dots], and then click **Add rule with code**.

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

> **Note**
>
> You can also click **More**, and then select **Edit code** to edit the rule using the appropriate [QPL syntax](#qpl-syntax).

. In the **Add/Edit ranking weight rule** panel, under **Ranking Factors**, drag the desired [ranking factors](https://docs.coveo.com/en/3412#ranking-factors) sliders to the desired [value](https://docs.coveo.com/en/3412#ranking-factor-value).

. Under **Condition**, you can optionally select a [query pipeline condition](https://docs.coveo.com/en/2793/) in the dropdown menu or [create a new one](https://docs.coveo.com/en/1959#create-a-condition).

. Under **Description**, optionally enter information that will help you manage the rule in the future.

. Click **Add rule** or **Save**.

## Duplicate ranking weight rules

When creating ranking weight 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.

. [Access the **Ranking Weights** subtab](#access-the-ranking-weights-subtab) in the query pipeline you want to manage.

. In the **Ranking weights** subtab, select the rules you want to duplicate within the same pipeline.

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

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

## Copy ranking weight rules to another pipeline

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

. [Access the **Ranking Weights** subtab](#access-the-ranking-weights-subtab) in the query pipeline you want to manage.

. In the **Ranking weights** subtab, 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 weight rules

. [Access the **Ranking Weights** subtab](#access-the-ranking-weights-subtab) in the query pipeline you want to manage.

. In the **Ranking weights** subtab, select the rules you want to delete.

. In the **Action** bar, click **More**, and then **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.

## Change the rule order

Query pipeline rules are executed in the order in which they appear on the page until a condition is satisfied.

. 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 manage the rules' execution order, and then click **Edit components** in the Action bar.

. On the page that opens, select the ranking weight tab.

. In the ranking weight tab, on the left side of the page, select pass:q,a[**ranking weight**].

. In the pass:q,a[**ranking weight**] subtab, click the rule whose position you want to change.

. In the Action bar, click **Move up** or **Move down** to change the position of the rule.

> **Note**
>
> When you move a ranking weight rule, only the order of execution of ranking weight rules is adjusted.
> Moving the rule doesn't affect the [order of execution](#order-of-execution) of ranking weight rules relative to other query pipeline components.

## Leading practices

### Use ranking weight rules conditionally

Add a [query pipeline condition](https://docs.coveo.com/en/2793/) to each ranking weight rule so that each rule only applies to the specific context in which you want to improve relevance.

### Use ranking weight rules sparingly

The pre-tuned ranking weights for each of the [ranking factors](#ranking-factors) used by Coveo [indexes](https://docs.coveo.com/en/204/) have been optimized over years of experience with a wide variety of indexed content to deliver well-balanced out-of-the-box relevance scores.
You can however adjust one or more of the available ranking factors when you see that the ranking of certain search results isn't ideal in a specific search context or case.

> **Important**
>
> Be careful when making adjustments. By default, all queries going through the pipeline will be affected.
> Fixing the ranking for a specific context may have undesired effects on other contexts.

### Test your ranking weight rules

When creating ranking weight rules, you should validate the effects of your ranking weight rule in the [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/) Debug Panel (see [rankingInfo section](https://docs.coveo.com/en/434#rankinginfo-section)).

## Ranking factors

You can tune the following ranking factors using the user interface options:

* [**Item last modification**](#item-last-modification)

* [**Keyword frequency**](#keyword-frequency)

* [**Keyword in concept**](#keyword-in-concept)

* [**Keyword in title**](#keyword-in-title)

* [**Keyword in summary**](#keyword-in-summary)

* [**Keyword proximity**](#keyword-proximity)

More options are available when defining ranking weight rules using the [QPL syntax](https://docs.coveo.com/en/3412#qpl-syntax).

> **Note**
>
> The relative weight of each of the available ranking factors isn't equal. Some weights affect the total ranking score more than others.
> Consequently, it may be difficult to predict and validate the effects of the changes you made to the ranking weight factors.

### Item last modification

The relevance score is increased for items with a more recent modification date.

> **Note**
>
> The `date` field is used as the item modification date.

### Keyword frequency

The relevance score is increased for items containing a higher number of keyword occurrences.
The boost increases proportionally to the number of times a keyword appears in an item relative to the number of times it appears in the index.

### Keyword in concept

The Coveo index uses a linguistic algorithm to create a list of the most important concepts found in an item.

Concepts take the form of keywords representing what you would find in the general content of the item.
These keywords are stored in the `concepts` field of an item.

The relevance score of the returned items is increased when the user query contains keywords which are present in the item's `concepts` field.

> **Notes**
>
> * For the **Keyword in concept** ranking factor to be modified by a ranking weight rule, the affected items must contain an [item body](https://docs.coveo.com/en/1847#item-body).
> 
> * Keywords in the `concept` field are extracted automatically by the index, and therefore it's not possible to manually add custom terms.

### Keyword in title

The relevance score is increased for items containing keywords in their title.
The boost increases as the proportion of title terms matching the query increases.

**Example**

An item with a title containing the exact keywords will have a higher relevance score boost than an item with a title containing only one of the keywords.

### Keyword in summary

When indexing an item, Coveo uses a linguistic algorithm that scans and extracts all the readable sentences of an item.
At query time, the algorithm relies on term frequency and proximity to select the sentences that best represent the query and creates an item summary made from those sentences.
The more the summary contains queried keywords, the higher the score.

> **Note**
>
> For the **Keyword in summary** ranking factor to be modified by a ranking weight rule, the affected items must contain an [item body](https://docs.coveo.com/en/1847#item-body).

### Keyword proximity

When a query includes more than one keyword, by default the relevance score is increased for items in which keywords appear close to each other. The boost increase is inversely proportional to the distance between the keywords in the item.

**Example**

An item containing keywords appearing side-by-side will have a higher relevance score boost than one containing the keywords dispersed in a paragraph.

## Ranking factor value

When applying a weight to a ranking factor, you must choose a value from **0* to *9** where:

* **5** is the default pre-tuned ranking factor value.

* **6* to *9**  progressively boosts the weight of a ranking factor relative to its pre-tuned value.

* **4* to *0**  progressively reduces the weight of a ranking factor relative to its pre-tuned value.

## QPL syntax

Use the following [query pipeline language (QPL)](https://docs.coveo.com/en/235/) syntax to manage ranking weight rules:

```text
rank <RANKING_FACTOR_CONFIGURATION>
```

### `<RANKING_FACTOR_CONFIGURATION>`

A comma-separated list of key-value pairs where each key must be a valid ranking factor and each [value](https://docs.coveo.com/en/3412#ranking-factor-value) must be an integer between 0 and 9 inclusively.

**Example**

```text
rank adjacency: 9, concept: 6, title: 5, termCasing: 1, uri: 0
```

Available keys are:

* [`adjacency`](#adjacency)

* [`concept`](#concept)

* [`customDocumentWeight`](#customdocumentweight)

* [`docDate`](#docdate)

* [`formatted`](#formatted)

* [`language`](#language)

* [`lastDirInUri`](#lastdirinuri)

* [`quality`](#quality)

* [`sourceReputation`](#sourcereputation)

* [`summary`](#summary)

* [`termCorrelation`](#termcorrelation)

* [`termCasing`](#termcasing)

* [`TFIDF`](#tfidf)

* [`title`](#title)

* [`uri`](#uri)

#### `adjacency`

The proximity of query terms in the item.

This key is the equivalent of the Administration Console's [**Keyword proximity**](https://docs.coveo.com/en/3412#keyword-proximity) ranking factor.

#### `concept`

Query terms in the automatically populated `@concepts` field for the item.

This key is the equivalent of the Administration Console's [**Keyword in concept**](https://docs.coveo.com/en/3412#keyword-in-concept) ranking factor.

#### `customDocumentWeight`

Custom weight assigned through an indexing pipeline extension for the item.

#### `docDate`

How recently the item was modified.

This key is the equivalent of the Administration Console's [**Item last modification**](https://docs.coveo.com/en/3412#item-last-modification) ranking factor.

#### `formatted`

The formatting of query terms in the item (for example, heading level, bold, large, etc.).

#### `language`

Whether the item is in the language of the search interface from which the query originates.

#### `lastDirInUri`

Query terms in the last part of the item URI.

#### `quality`

The proximity of the item to the root of the indexed system.

#### `sourceReputation`

The rating of the source the item resides in.

#### `summary`

Query terms in the summary of the item.

This key is the equivalent of the Administration Console's [**Keyword in summary**](https://docs.coveo.com/en/3412#keyword-in-summary) ranking factor.

#### `termCorrelation`

Query term correlations within stemming classes in the item.

#### `termCasing`

Query term casing in the item.

#### `TFIDF`

Term frequency-inverse document frequency.

This key is the equivalent of the Administration Console's [**Keyword frequency**](https://docs.coveo.com/en/3412#keyword-frequency) ranking factor.

#### `title`

Query terms in the title of the item.

This key is the equivalent of the Administration Console's [**Keyword in title**](https://docs.coveo.com/en/3412#keyword-in-title) ranking factor.

#### `uri`

Query terms in the URI of the item.

## 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 weight rules.
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 weight rules
|Organization - Organization  
Search - Query pipelines
|View

.2+|Edit ranking weight rules
|Organization - Organization
|View

|Search - Query pipelines
|Edit
|===