Rankingweight - Query pipeline feature

In this article

A query pipeline statement expressing the rankingweight query pipeline feature allows you to individually fine-tune the weight of one or more of the ranking factors used by the index to determine the ranking scores of query result items.

Leading practice

Typically, a statement expressing the rankingweight feature should only apply when a certain condition is fulfilled.

In general, you should ensure that this is the case by associating such a statement, and/or the query pipeline it’s defined in, to a global condition.


In the Coveo Administration Console, you can manage statements expressing the rankingweight feature from the Ranking Weights tab (see Manage ranking weight rules).

The following diagram shows the process of a query being sent to the Search API and the order of execution of query pipeline features.

Apply rankingWeights statements


Use the following query pipeline language (QPL) syntax to define a statement expressing the rankingweight feature:

rank <rankingFactorConfiguration>


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.

The following table lists the available keys (that is, ranking factors):

Ranking factor Determines how to modify the relevance score of a query result item based on
adjacency The proximity of query terms to one another in the item.
concept Query terms in the automatically populated @concepts field for the item.
customDocumentWeight Custom weight assigned through an indexing pipeline extension for the item.
docDate How recently the item was modified.
formatted How query terms are formatted 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.
termCorrelation Query term correlations within stemming classes in the item.
termCasing Query term casing in the item.
TFIDF Term frequency-inverse document frequency.
title Query terms in the title of the item.
uri Query terms in the URI of the item.

The following table illustrates how setting a certain ranking factor to a certain value impacts the relative weight of that ranking factor:

Value Impact on ranking factor weight
0 Minimum weight
1 Reduced weight
5 Default weight
6 Increased weight
9 Maximum weight


You create a global condition with the following QPL definition:

Global condition:

when $searchHub is "Agents"

In an empty query pipeline named Testing Rankingweight, you create a statement expressing the rankingweight feature with the following QPL definition:


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

You associate this statement to the global condition statement you created before.

A user performs a query against your index with the following payload:

Query payload:

  "pipeline": "Testing Rankingweight",
  "q": "need help with the rankingweight feature",
  "searchHub": "Agents"

Since this query goes through the Testing Rankingweight query pipeline and satisfies the condition of your statement, the statement is applied. As a result, the following things happen:

  • The adjacency ranking factor weight is set to its maximum possible value.

    Therefore, an item containing query terms in close proximity to one another will receive a considerable ranking score boost.

  • The concept ranking factor weight is slightly increased.

    Therefore, an item whose @concepts field contains query terms will receive a somewhat higher than usual ranking score boost.

  • The title ranking factor weight retains its default value.

    Therefore, omitting the title: 5 key-value pair in the statement definition would have been perfectly equivalent.

  • The termsCasing ranking factor weight is substantially reduced.

    Therefore, whether query terms appearing in an item do match the original casing of the query or not will have very little impact on the ranking score of that item.

  • The uri ranking factor weight is set to its minimum possible value.

    Therefore, query terms appearing in the URI of an item will have next to no impact on the ranking score of that item.

  • All other ranking weights retain their own default value.