Manage Ranking Expression Rules

A Coveo-powered search interface typically sorts query results by relevance. This means that items with high ranking scores normally appear at the top of the results list.

When you have the required privileges, you can use the Result Ranking tab of a query pipeline configuration to define query pipeline ranking expressionrules to exercise direct control over item ranking scores.

EXAMPLE

You want to promote ACME monitors in a Coveo-powered commerce portal.

In the portal’s query pipeline, you define a ranking expression rule that adds a positive modifier to the ranking score of each result item whose @brand field value is ACME when the query contains monitor or screen.

1690 PromoteACMEMonitors

An end user accesses the commerce portal and submits the following query: globex computer screen.

Even though the end user is apparently looking for monitors of the Globex brand, your ranking expression rule is now likely to make ACME monitors appear higher in the result list.

Common Use Cases

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

EXAMPLE

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

Enforce a Business Rule

EXAMPLE

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

Demote Content Intended for Another Audience

EXAMPLE

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

Demote Legacy Content

EXAMPLE

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

Create Ranking Expression Rules

  1. On the Query Pipelines page, click the query pipeline in which you want to add a rule, and then in the Action bar, click Edit Components.

  2. On the page that opens, select the Result Ranking tab, and then, in the upper-right corner, click Add Rule.

  3. In the Add Ranking Rule modal that opens, select Ranking expression, and then click Add Rule.

  4. In the Name input, enter a name for your rule.

  5. (If available)[1] In the Assign to a rules group or campaign section, if you want the rule to be part of a group of rules, optionally select the desired group in the drop-down menu. You can also create a new group by clicking Create a new group.

  6. Under If query:

    1. Select an operator.

    2. In the Enter keyword(s) input, enter an expression (keywords or a regex) that will trigger the rule.

    3. Select the language of your expression, or All languages if your expression is susceptible to appear in all languages (e.g., a product number).

    4. If you want your query to match your expression in other languages, repeat the previous steps with this expression in other languages.

    EXAMPLE
    If query contains "maple syrup" in English
  7. Under Content matching these expressions, enter the desired expressions.

  8. Under Will have its score changed by, move the slider to lower or boost the score of items that meet the specified query expressions.

    Avoid using modifiers greater than 100 or lower than -100, unless you want to completely override the index ranking scores.

    If you want to make a specific item appear at the top of the search results, you should consider using featured result rules instead.

  9. Under User note, optionally enter a text with information that will help you and your colleagues to manage the rule in the future.

  10. On the right-hand side, under Condition, you can optionally select a query pipeline condition in the drop-down menu or create a new one.

  11. Review your ranking expressions in the Preview test search page. Note that the customizations you made in the Interface Editor and your search page code don’t apply in this preview.

  12. Click Add Rule. The new rule is effective immediately.

Edit Ranking Expression Rules

  1. On the Query Pipelines page, click the query pipeline in which you want to edit a rule, and then in the Action bar, click Edit Components.

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

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

  4. In the Name input, enter a name for your rule.

  5. (If available)[1] In the Assign to a rules group or campaign section, if you want the rule to be part of a group of rules, optionally select the desired group in the drop-down menu. You can also create a new group by clicking Create a new group.

  6. Under If query:

    1. Select an operator.

    2. In the Enter keyword(s) input, enter an expression (keywords or a regex) that will trigger the rule.

    3. Select the language of your expression, or All languages if your expression is susceptible to appear in all languages (e.g., a product number).

    4. If you want your query to match your expression in other languages, repeat the previous steps with this expression in other languages.

    EXAMPLE
    If query contains "maple syrup" in English
  7. Under Content matching these expressions, enter the desired expressions.

  8. Under Will have its score changed by, move the slider to lower or boost the score of items that meet the specified query expressions.

    Avoid using modifiers greater than 100 or lower than -100, unless you want to completely override the index ranking scores.

    If you want to make a specific item appear at the top of the search results, you should consider using featured result rules instead.

  9. Under User note, optionally enter a text with information that will help you and your colleagues to manage the rule in the future.

  10. On the right-hand side, under Condition, you can optionally select a query pipeline condition in the drop-down menu or create a new one.

  11. Review your ranking expressions in the Preview test search page. Note that the customizations you made in the Interface Editor and your search page code don’t apply in this preview.

  12. Click Save. The edited 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.

For the complete parameter definitions, see Update a result ranking rule.

  1. On the Query Pipelines page, click the query pipeline for which you want to modify existing query pipeline rules, and then in the Action bar, click Edit components.

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

  3. In the Result Ranking tab, click the rule you want to modify.

  4. In the Action bar, click Edit JSON.

  5. In the Edit a Ranking Expression JSON Rule subpage, make the desired modifications.

  6. Click Save.

EXAMPLE
{
  "name": "My Ranking Expression",
  "kind": "ranking_expression",
  "defaultMatchOperator": {
    "kind": "is"
  },
  "predicates": [
    {
      "kind": "basicExpressionAndLocalePredicate",
      "basicQueryExpression": "Hello",
      "matchOperator": {
        "kind": "is"
      },
      "locale": {
        "kind": "specific",
        "code": "en"
      }
    },
    {
      "kind": "basicExpressionAndLocalePredicate",
      "basicQueryExpression": "Bonjour",
      "matchOperator": {
        "kind": "is"
      },
      "locale": {
        "kind": "specific",
        "code": "fr"
      }
    }
  ],
  "targets": [
    {
      "queryExpression": "@filtetype==html"
    }
  ],
  "condition": {
    "reference": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  },
  "isMigrated": false,
  "description": "This is a ranking expression rule",
  "rankingModifier": 250,
  "enabled": true,
  "associatedGroup": {
    "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "name": "myGroup",
    "isActive": true
  }
}

Duplicate Ranking Expression Rules

  1. On the Query Pipelines page, click the query pipeline for which you want to duplicate query pipeline rules, and then in the Action bar, click Edit components.

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

  3. In the Result Ranking tab, click the rule you want to duplicate within the same pipeline (typically to create a slightly different rule).

  4. In the Action bar, click Duplicate.

The duplicated rule appears at the bottom of the list in the pipeline component tab.

Delete Ranking Expression Rules

  1. On the Query Pipelines page, click the query pipeline for which you want to delete query pipeline rules, and then in the Action bar, click Edit components.

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

  3. In the Result Ranking tab, click the rule that you want to delete.

  4. In the Action bar, click Delete.

  5. Click Delete to confirm.

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 you need to enforce specific or temporary business rules which Coveo Machine Learning (Coveo ML) 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 can eventually learn from those positive outcomes.

Use Ranking Expression Rules Sparingly

Maintaining a large number of 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.

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. 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 to each 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 to improve relevance directly in your index. Also avoid creating rules that are too specific; if a rule merely applies to an insignificant volume of queries (e.g., one or two queries per month), it will likely not produce enough compelling usage analytics data 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 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.

Reference

Operators

Contains

For the ranking expressions to modify the ranking score of the search results of an end user, the expression entered in the Enter keyword(s) input must 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 entered in the Enter keyword(s) input must be the same as 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 Enter keyword(s) input.

Expressions

The Coveo Cloud query syntax expressions whose result items should have their ranking scores modified by the rule.

When the rule applies, a distinct query ranking expression (QRE) is generated for each of those expressions.

Expected type (QPL): list of query-expressions

EXAMPLE
  • @brand==ACME

  • @audience==$context.userRole

When a rule contains an expression referencing a QPL object (e.g., @audience==$context.userRole), associate that rule with a query pipeline condition validating that the QPL object is populated with some value (e.g., when $context.userRole isPopulated). Otherwise, you risk modifying the ranking scores of unexpected items, as non-populated QPL objects are evaluated to the NOT operator.

Order of Execution

The following diagram highlights in orange the position of ranking expression rules in the overall order of execution of query pipeline features.

ranking expression rules in the query pipeline order of execution

Required Privileges

By default, members of the Administrators and Relevance Managers built-in groups can view and edit elements of the Query Pipelines page.

The following table indicates the required privileges to view or edit elements of the Query Pipelines page (see Manage Privileges and Privilege Reference).

Action Service - Domain Required access level

View ranking expressions

Search - Query pipelines

View

Edit ranking expressions

Search - Query pipelines

Edit


1. The Assign to a rules group or campaign section isn’t available for all Coveo organizations. See Manage Groups & Campaigns for further information.
Recommended Articles