Manage ranking weight rules

This is for:

Developer System Administrator

A Coveo index uses a number of ranking factors to evaluate the relevance score of each search result for a given query. When the search interface sorting is set to Relevance, the search results are presented in descending relevance score order to present the most pertinent items at the top.

Members with the required privileges can configure query pipeline ranking weight rules to fine-tune one or more of the pre-tuned ranking factors for a specific query pipeline.

Prerequisites

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

Once you meet these requirements, you can create a rule on the Query Pipelines (platform-ca | platform-eu | platform-au) page. To test the rule, use the A/B test feature to compare the results of the rule with the results of the original pipeline.

Create ranking weight rules

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline in which you want to add a rule, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Ranking weights.

  4. In the upper-right corner of the page, click Add Rule to access the Add a Ranking Weight Rule [1] subpage.

  5. Under Ranking Factors, drag the desired ranking factors sliders to the desired value.

  6. On the right side, under Condition, you can optionally select a query pipeline condition in the dropdown menu or create a new one.

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

  8. Click Add rule.

Edit ranking weight rules

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline in which you want to edit a rule, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Ranking weights.

  4. Click the rule you want to edit, and then click Edit in the Action bar [2] to access the Edit a Ranking Weight Rule subpage.

  5. Under Ranking Factors, drag the desired ranking factors sliders to the desired value.

  6. On the right side, under Condition, you can optionally select a query pipeline condition in the dropdown menu or create a new one.

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

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

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to duplicate rules, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Ranking weight.

  4. In the Ranking weight subtab, select each checkbox next to the rules you want to duplicate within the same pipeline.

  5. 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 more than one query pipeline that serve different purposes but require similar rules, you may want to copy ranking weight rules from one pipeline to another.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline from which you want to copy rules, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Ranking weight.

  4. In the Ranking weight subtab, select each checkbox next to the rules you want to copy to another pipeline.

  5. In the Action bar, click More, and then click Copy to…​.

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

Review information about the rule’s creation or last modification

You can verify who created or last modified a given ranking weight rule by inspecting the Details column of the Result Weights subtab. The Details column also indicates the hour and date the rule was created or last modified.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline containing the rule for which you want to inspect the information of the Details column, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Result Weights.

  4. In the Result Weights subtab, inspect the information of the Details column for the desired rule.

Delete ranking weight rules

You can delete ranking weight rules from a query pipeline.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to delete rules, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Ranking weights.

  4. In the Ranking weights subtab, select each checkbox next to the rules you want to delete.

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

  6. Click Delete to confirm.

Change the rule order

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

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to manage the rules' execution order, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Ranking weights.

  4. In the Ranking weights subtab, click the rule whose position you want to change.

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

Leading practices

Use ranking weight rules conditionally

Add a query pipeline condition 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 used by Coveo indexes 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 Debug Panel (see rankingInfo section).

Reference

Ranking factors

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

More options are available when defining ranking weight rules using the 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, as shown below.

what a concepts field looks like and the values it may contain

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.

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

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 recommended 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) syntax to manage ranking weight rules:

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 must be an integer between 0 and 9 inclusively.

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

Available keys are:

adjacency

The proximity of query terms in the item.

This key is the equivalent of the Administration Console’s 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 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 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 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 ranking factor.

title

Query terms in the title of the item.

This key is the equivalent of the Administration Console’s Keyword in title ranking factor.

uri

Query terms in the URI of the item.

Order of execution

The following diagram illustrates the overall order of execution of query pipeline features:

diagram showing order of execution

Required privileges

By default, members with the required privileges can view and edit elements of the Query Pipelines (platform-ca | platform-eu | platform-au) page.

The following table indicates the required privileges for members to view or edit ranking weight rules (see Manage privileges and Privilege reference).

Action Service - Domain Required access level

View ranking weight rules

Organization - Organization
Search - Query pipelines

View

Edit ranking weight rules

Organization - Organization

View

Search - Query pipelines

Edit
1. (Advanced) You can click Menu, and then select Add rule with code to define the rule using the appropriate QPL syntax.
2. (Advanced) You can click More, and then select Edit code to edit the rule using the appropriate QPL syntax.