Adding and Managing Query Pipeline Featured Results

Featured result rules force specific items to appear at the top of the result list whenever a query satisfies a given condition. You can also use them to force certain items to 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 Featured Results tab of a query pipeline configuration.

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

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

1961-acme-example

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.

  1. On the Query Pipelines page, double-click the query pipeline in which you want to create or edit featured result rules, and then select the Featured Results tab.

  2. Depending on whether you want to add or edit a featured result rule:

    • Click Add Featured Result to access the Add a Rule subpage.

      OR

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

    1961-featured-results

  3. In the Name box, enter a name for your featured result rule (see “Name” Box Reference).

  4. Under If query:

    1. Select an operator.

    2. Enter an expression (keywords or a regex) that will trigger the featured result 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.

      If query contains "maple syrup" in English, "sirop d'érable" in French, and "Ahornsirup" in German

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

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

  6. Back on the Add/Edit a Featured Result Rule 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).

  7. 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. Only queries meeting this condition and at least one of your If query requirements will return the featured result.

  8. Review your featured results in the Preview test search page. Keep in mind, however, that the customizations you made in the Interface Editor and your search page code don’t apply in this preview.

  9. Click Add Rule/Save.

You must sort search results by Relevance in your search interface to see featured results at the top of the result list.

Editing a featured result JSON configuration is especially useful when you want to implement a rule that doesn’t fit with the parameters available in the Add/Edit a Rule subpage.

  1. On the Query Pipelines page, double-click the query pipeline in which you want to edit featured result rules, and then select the Featured Results tab.

  2. In the Featured Results tab, click the rule you want to edit.

  3. In the Action bar, click More, and then select Edit JSON.

  4. On the Edit a Featured Result JSON Rule subpage, enter a JSON configuration defining your featured result rule. Typically, your JSON code should be similar to the following example. See Update a featured result rule in the Coveo Cloud V2 Search API documentation for parameter definitions.

     {
         "name": "hello world",
         "defaultMatchOperator": {
             "is": {}
         },
         "predicates": [
             {
             "basicQueryExpression": "hello",
             "matchOperator": {
                 "is": {}
             },
             "locale": {
                 "specific": {
                 "code": "en"
                 }
               }
             },
             {
             "basicQueryExpression": "bonjour",
             "matchOperator": {
                 "is": {}
             },
             "locale": {
                 "specific": {
                 "code": "fr"
                 }
               }
             }
         ],
         "targets": [
             {
             "uniqueId": "a6bf1757fff057f266b697df9cf1769c17e047f58f9220a7008d4f18152f"
             }
         ],
         "condition": {
             "reference": "a928311e-e618-4022-a583-d4b1170a4b53"
         },
         "matchQuery": false,
         "matchAdvancedQuery": true,
         "includeInFacets": false,
         "isMigrated": false,
         "description": ""
     }
    
  5. Click Save.

  1. On the Query Pipelines page, double-click the query pipeline in which you want to duplicate featured result rules, and then select the Featured Results tab.

  2. In the Featured Results tab, click the rule you want to duplicate within the same pipeline (typically to create a slightly different rule).

  3. In the Action bar, click Duplicate.

The duplicated rule appears at the bottom of the list.

  1. On the Query Pipelines page, double-click the query pipeline in which you want to delete featured result rules, and then select the Featured Results tab.

  2. In the Featured Results tab, click the rule you want to delete.

  3. In the Action bar, click Delete.

  4. Click Delete to confirm.

Reference

“Name” Box

If you don’t provide a name for your featured result rule, the Name box is automatically filled with either:

If your featured result rule contains both selected items and query expressions, the Name box is automatically populated with the one you selected first.

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) box 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) box 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) box.

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

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

The search page uses the empty pipeline rather than the actual pipeline in which you’re adding the featured result. It’s thus strongly recommended to test your rule in 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 field1 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.

    1: The selected field must have the Facet and Use cache for nested queries field options selected.

  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.

    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 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 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 box, 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.

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 further information on advanced query expressions, see Advanced Query Expression (aq).

Order of Execution

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

Apply featured result rules

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 and associated panels (see Privilege Management and Privilege Reference).

Action Service - Domain Required access level
View featured results

Search - Query pipelines

View
Edit features results

Search - Query pipelines

Edit
Recommended Articles