Manage Featured Result Rules

Featured result rules make specific items appear at the top of the result list whenever a query satisfies a given condition. You can also use them to make certain items appear at the top of the result list regardless of the query.

When you have the required privileges, you can set featured result rules in the Result Ranking tab of a query pipeline configuration.

EXAMPLE

You want to promote your best-selling ACME monitor model in a Coveo-powered commerce portal when users search for that specific brand.

Therefore, you create a featured result rule in which you associate your best-selling ACME monitor model with the query ACME.

1961-acme-example

Common Use Cases

Among other things, you can use featured result rules to improve the visibility of new items or to promote items in specific contexts.

Improve the Visibility of New Items

EXAMPLE

A new key knowledge article is available for your support agents. You want this article to be displayed at the top of the results list whenever an agent’s query contains deflection before Coveo Machine Learning (Coveo ML) Automatic Relevance Tuning (ART) can automatically boost the article.

Administration Console capture of a featured result rule

Promote Items in Specific Contexts

EXAMPLES
  • In your sports supplies Coveo-powered commerce interface, you want to liquidate last year’s ACME branded hockey sticks to make room for the new model in your warehouse. You therefore create a featured result rule to make last year’s ACME hockey sticks appear at the top of the search results whenever a query contains stick or ACME.

Administration Console capture of a featured result rule
  • In your Coveo-powered intranet portal, you want to display the new security policy training that must be completed by all employees before a certain deadline. You therefore create a featured result rule to make the document appear at the top of the search results regardless of the employee’s query.

Administration Console capture of a featured result rule
  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 Featured result, 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 Show this, click Add indexed items, and then click either "Select an Item" to select items to feature at the top of the search results or "Add a query expression" to add a query expression whose matching items will appear at the top of the search results.

  8. When you’re done selecting the desired items, click Add Items.

  9. Back on the Add Featured Result subpage, under Match advanced query, select True or False to determine whether featured items should only be displayed when matching the advanced query expression (aq) (see "Match Advanced Query" Section).

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

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

  12. Review your featured results 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.

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

  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 Show this, click Add indexed items, and then click either "Select an Item" to select items to feature at the top of the search results or "Add a query expression" to add a query expression whose matching items will appear at the top of the search results.

  8. When you’re done selecting the desired items, click Add Items.

  9. Back on the Edit Featured Result subpage, under Match advanced query, select True or False to determine whether featured items should only be displayed when matching the advanced query expression (aq) (see "Match Advanced Query" Section).

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

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

  12. Review your featured results 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.

  13. Click Save. The edited rule is effective immediately.

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 featured result 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 Featured Result JSON Rule subpage, make the desired modifications.

  6. Click Save.

EXAMPLE
{
    "name": "My Featured Result",
    "kind": "featured_result",
    "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": [
        {
        "uniqueId": "a6bf1757fff057f266b697df9cf1769c17e047f58f9220a7008d4f18152f"
        }
    ],
    "condition": {
      "reference": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
    },
    "matchQuery": false,
    "matchAdvancedQuery": false,
    "includeInFacets": true,
    "isMigrated": false,
    "description": "This is a featured result rule",
    "enabled": true,
    "associatedGroup": {
      "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "name": "myGroup",
      "isActive": true
    }
  }
  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.

  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 featured result rules.

While adding or editing a featured result rule, you can use the right-hand side Preview test search page to ensure that your rule executes as expected.

Give Visibility to Your Promoted Results

You may want the results promoted by a featured result to be clearly identified in the search result list. You can accomplish this by adding result badges to query result items in your search interface.

You can also specify a condition to a specific result template.

When a query pipeline contains Coveo Machine Learning (Coveo ML) models, avoid or minimize the use of featured result rules. These rules are static and can negatively impact Coveo ML models which follow trends.

Reference

Operators

Contains

For the featured results to be displayed in 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 featured results to be displayed in 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 featured results to be displayed in the search results of an end user, their query must match the regular expression (regex) entered in the Enter keyword(s) input.

EXAMPLE

You want to always have a specific article at the top of the search results when a user opens your Knowledge Base search page, so you select the Matches operator and provide the following regex: ^$.

"Show This" Section

"Select an Item" Search Page

On the Select an Item search page, find and click the desired item.

The search page uses an empty pipeline rather than the actual pipeline in which you’re adding the featured result. Therefore, it’s strongly recommended to test your rule on the Preview test search page before adding or saving the rule.

If your index contains several equivalent versions of the item in different languages, and if the item is not a Salesforce knowledge article (for which the multilanguage feature is handled automatically), check the Multilanguage box, and then:

  1. In the Family field drop-down menu, select a facet field[2] whose value is common to the selected item and its other language versions, and to these items only. This value identifies the corresponding items as a family, i.e., a group of identical items in different languages.

  2. In the Language field drop-down menu, select a field indicating the language of the item.

    • Only ISO 639-1 language codes are supported (see List of ISO 639-1 codes). The field value may include an additional regional code (e.g., US in en-US), but this information will be ignored as it isn’t relevant for this feature.

    • In a family of items to feature, if no item has a language field value matching the language of the query, the English version of the item is displayed by default.

  3. Repeat for each language version of the item.

    EXAMPLE

    You have a multilanguage commerce website on which each product has a page. Each product therefore corresponds to several items in your index, one for each language in which the product page can appear. In your item metadata, the value of the @productnumber field is identical for all language versions of a product page, while the value of the @productpagelanguage field indicates the language of the product page (e.g., en stands for English, fr for French, etc).

    So, for the English item Maple Syrup Candy, you select @productnumber as the Family field and @productpagelanguage as the Language field. You then do the same for the French version Bonbons au sirop d’érable. Since they represent the same product, these items have the same value in the @productnumber field, which identifies them as a group of identical items in different languages. The @productpagelanguage field, however, identifies the language of each item in the family.

    As a result, when an end user queries Bonbons au sirop d’érable, the Coveo Search API recognizes this query as a French query, and looks in the corresponding family of product items for the French version to display as a featured result.

"Add a Query Expression" Panel

In the Expression input, enter a query expression for which matching items must be returned as featured results (see Understanding the Query Expression).

“Match Advanced Query” Section

By default, featured results are typically not distinguishable from other results in search interfaces. If a featured result is an item outside of the expected scope, users may be confused or even think that there are bugs in the search interface. Therefore, the Match advanced query parameter is set to True by default.

EXAMPLE

You have a bicycle part retail website on which you sell parts for mountain, road, and hybrid bicycles. At the top of your product search page, there are three tabs, which customers can select to see only products related to the type of bicycle they ride. When a tab is selected, the advanced query expression value changes to @biketype=="mountain", @biketype=="road", or @biketype=="hybrid".

You create a featured result rule to promote your best-selling hybrid tire when customers search for tire. In this item metadata, the @biketype field has the hybrid value.

Since this product doesn’t suit mountain and road bicycles, it should not appear in the search results of users riding such bicycles. You therefore set the Match Advanced Query parameter to True so that this featured result is displayed only when its value for the @biketype field matches that of the advanced query expression. In other words, for the featured result rule to apply and this item to appear in the search results, the Hybrid tab must be selected.

As a result:

  • When a user searches for tire in the Mountain and Road tabs, your featured result doesn’t appear, since it doesn’t match the interface scope.

  • When a user searches for tire in the Hybrid tab, and then switch to another tab, your featured result disappears, as it isn’t relevant in the new interface scope.

For more information on advanced query expressions, see Advanced Query Expression (aq).

Order of Execution

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

featured result 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 featured results

Search - Query pipelines

View

Edit featured results

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.
2. The selected field must have the Facet field option selected.
Recommended Articles