Ranking expression: Query pipeline feature

This is for:

Developer System Administrator

A query pipeline statement defining the ranking expression query pipeline feature generates query ranking expressions (QRE) to increase or decrease the ranking scores of items appearing in certain query result sets by a specific amount. You can configure a ranking expression statement in a query pipeline using the Result Rankings API. Unlike featured results that apply large boosts for top placement, ranking expressions use moderate adjustments by targeting items matching specific metadata expressions to fine-tune relevance.

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

Coveo | diagram showing order of execution

How ranking expressions work

When a ranking expression statement is applied in a query pipeline, the following happens:

  • Items matching the <expression> have their ranking scores increased or decreased by the amount specified in the <modifier>.

  • The modifier value is multiplied by 10 to determine the ranking score adjustment for each matching item. For example, a modifier value of 100 adds 1000 to the ranking score of each matching item.

  • Multiple ranking expression statements can apply to the same query. The ranking score adjustments from all applicable statements are cumulative.

    Note

    Unlike featured results, ranking expressions don’t modify the dq (disjunction) part of the combined query expression. They only adjust the ranking scores of items already in the result set — they can’t guarantee an item appears in results. To guarantee top placement, use featured result statements instead.
Important

While the <modifier> accepts values in the range [-1000000, 1000000], avoid modifiers greater than 100 or lower than -100, as this can completely override the natural relevance ranking from the index. Extreme modifiers can cause items with poor natural relevance to appear higher than highly relevant items.

To make a specific item appear at the top of the search results, use featured result statements instead.

When and why to use ranking expressions

Use ranking expressions when you need to fine-tune relevance by adjusting ranking scores based on item metadata:

  • Boost recent content

    Prioritize items published or updated within a specific time to keep users informed with the latest information.

  • Promote specific item types

    Elevate articles, user guides, or troubleshooting content when they’re more valuable for certain queries.

  • Prioritize certain metadata

    Adjust scores based on language, author, category, or custom fields that indicate quality or relevance.

  • Enforce business rules

    Temporarily boost items related to current campaigns, product launches, or organizational priorities.

  • Fine-tune for specific contexts

    Adjust relevance differently based on user context, search interface, or pipeline conditions.

Tip
Leading practice

Typically, a ranking expression statement should only apply when a condition is fulfilled.

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

When basing a ranking expression statement on the value of one or more $context keys, you should use a condition to assert that those keys contain values. Otherwise, the statement won’t apply as expected.

For example:

Condition

when $query contains "troubleshooting"

Statement

boost `@documenttype==Article` by 50

Syntax

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

boost `<expression>` by <modifier>

<expression>

A query expression enclosed in backticks that identifies which items should have their ranking scores modified, such as @documenttype==Article or @title/="^.troubleshoot.$". The backticks are used by the QPL parser to recognize and validate the content as a query expression. Items matching this expression have their ranking scores increased or decreased by the amount specified in the <modifier> parameter.

<modifier>

An integer value specifying how much to adjust the ranking scores of items matching the <expression>.

  • A positive value increases ranking scores (boosts items higher in results).

  • A negative value decreases ranking scores (demotes items lower in results).

Example

In this example, you want to boost user guides and recent content when a user searches for "product guide" in the Product Support query pipeline.

You first create a condition at the organization level with the following request:

Request:

POST /rest/search/v1/admin/pipelines/statements

Request body:

{
  "definition": "when $query contains \"product guide\"",
  "description": "Applies when query contains 'product guide'"
}

Response (excerpt):

{
  "id": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e"
}

You then create two ranking expression statements in the Product Support pipeline and associate them with the condition you created:

Request:

POST /rest/search/v1/admin/pipelines/{pipelineId}/statements

Request body:

{
  "feature": "ranking",
  "definition": "boost `@documenttype==UserGuide` by 75",
  "description": "Boost user guides",
  "parent": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e"
}

Request:

POST /rest/search/v1/admin/pipelines/{pipelineId}/statements

Request body:

{
  "feature": "ranking",
  "definition": "boost `@date>=today-30d` by 25",
  "description": "Boost recent content",
  "parent": "45a7892e-a63f-4c8e-8795-ab38c8c18d7e"
}

The parent field links each statement with the condition. The statements only apply when the condition is met.

When a user performs a query with the following payload, both statements apply:

{
  "aq": "@language==en",
  "pipeline": "Product Support",
  "q": "product guide installation"
}

Since this query goes through the Product Support query pipeline and satisfies the condition of both statements, those statements apply. As a result, the ranking scores of certain items are modified:

  • Items with @documenttype==UserGuide have their ranking scores boosted by modifier 75.

  • Items with @date>=today-30d (published in the last 30 days) have their ranking scores boosted by modifier 25.

  • Items that match both expressions (user guides published in the last 30 days) receive a cumulative boost from both modifiers (75 + 25).

Unlike featured results, the ranking expression statements don’t modify the query expression itself:

  • q (that is, $query) remains product guide installation.

  • aq (that is, $advancedQuery) remains @language==en.

The ranking expression statements only adjust the ranking scores of items matching the specified expressions, making them appear higher (or lower, for negative modifiers) in the result list based on their relevance and the applied boosts. Items that match the query but don’t match any ranking expression keep their original ranking scores calculated by the index.

Leading practices

Consider the following leading practices when using ranking expression statements:

Use ranking expressions for legitimate reasons

ranking expression statements are especially useful when enforcing specific or temporary business rules which Coveo Machine Learning (Coveo ML) could otherwise hardly deduce from natural end-user behavior.

By adjusting the ranking scores of certain result items when needed, your goal is to lead end users to the most contextually relevant content so that your Coveo ML models can learn from those positive outcomes.

Keep modifiers moderate

Avoid using modifiers greater than 100 or lower than -100, as this can completely override the natural relevance ranking from the index. Extreme modifiers can cause items with poor natural relevance to appear higher than highly relevant items.

To guarantee that specific items appear at the top of search results, use featured result statements instead of ranking expressions. Featured results ensure that specific items appear at the top of results regardless of their natural relevance score, whereas ranking expressions only adjust scores for items already in the result set.

Test with different modifier values

You can use the Preview test search page in the Coveo Administration Console to adjust the modifier value and see its effect on ranking scores in real time. Use this to find the optimal modifier value for your use case.

What’s next

Test your ranking expression rules by performing queries that satisfy the associated conditions and verifying that the expected items are boosted or demoted in the search results as intended.