Adding and Managing Query Pipeline Featured Results

Featured results query pipeline statements are rules that force specific items to appear at, or near, 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 an end user’s query.

Members of the Administrators and Relevance Managers built-in groups can set these rules in the Featured Results tab of a query pipeline configuration. Configuring featured results also allows you to add promoted results badges to items in your search interface.

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

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

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

Apply featured result rules

  1. If not already done, log in to your Coveo Cloud organization as a member of a group with the required privileges to manage query pipeline components in the target Coveo Cloud organization.

  2. In the main menu on the left, under Search, select Query Pipelines.

  3. On the Query Pipelines page, access the query pipeline in which you find the featured result rules you want to manage:

    • Double-click the pipeline.

      OR

    • Click the pipeline, and then in the Action bar, click Edit components.

  4. On the selected pipeline page, select the Featured Results tab.

Members with the privilege to view query pipelines (i.e., the View all or the Custom access level on the Query Pipelines domain) can review featured result rules in read-only mode (see Privilege Management and Query Pipelines Domain).

The query pipeline featured result management procedure varies depending on when your organization was created (see Organization ID and Other Information) If it was created after June 10, 2019, see Organization Created After June 10, 2019. If it was created before June 10, 2019, see Organization Created Before June 10, 2019.

Organization Created After June 10, 2019

In the Featured Results tab, you can add or edit a featured results rule (see Access the “Featured Results” tab of a Pipeline):

  1. Depending on whether you want to add or edit a featured results rule:

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

      OR

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

  2. On the Add/Edit a Featured Result Rule page:

    1. In the Name box, enter a name for your featured result rule.

      If you do not provide a name for your featured result rule at this step, 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.

    2. Under If query:

      1. Select an operator. Your options are:

        • Contains

          For the featured results to be displayed in the search results of an end-user, the expression you will enter next must be part of the end-user’s query.

        • Is

          For the featured results to be displayed in the search results of an end-user, this user’s query must be the exact expression you will enter next.

        • Matches

          (For advanced users) For the featured results to be displayed in the search results of an end-user, this user’s query must match the regular expression (regex) you will enter next.

          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: ^$.

      2. Enter an expression (keywords or 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., if it is 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

    3. Under Show this, click Add indexed items to either select items to feature at the top of the search results or add a query expression whose matching items will appear at the top of the search results.

    4. In the Add Indexed Items panel, depending on the action you want to accomplish, click Select an Item or Add a query expression.

      1. If you selected Select an Item, in the search page that appears, find and click the desired item.

        The search page uses the empty pipeline rather than the actual pipeline in which you are adding the featured result. It is thus strongly recommended to test your rule in the Preview section 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 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 is not relevant for this feature.

        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.

      2. If you selected Add a query expression, in the box that appears, enter a query expression for which matching items must be returned as featured results.

    5. When you are done selecting the desired items, click Add Items.

    6. Back on the Add a Featured Result Rule page, under Match advanced query, select True or False to determine whether featured items should only be displayed when matching the advanced query expression (aq), i.e., the search interface scope, facet selection, and other hidden or user-selected filters (see Advanced Query Expression).

      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 does not 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 does not appear, since it does not 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 is not relevant in the new interface scope.

    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 (see Create a Condition). Only queries meeting this condition and at least one of your If query requirements will return the featured results.

    8. Review your featured results in the test search page. Keep in mind, however, that the customizations you made in the Interface Editor and your search page code do not apply in this preview (see Interface Editor and Code View).

    9. Click Add Rule/Save.

You index your product catalog, which is available in several languages, and each product datasheet is indexed as an item. For each product, you therefore have several indexed items, which correspond to the different language versions of the product datasheet.

So, when promoting a product datasheet as a featured result, you want to display the datasheet version corresponding to the language in which the end user queried the product name. For instance, if the end user queries the French product name, the featured result should be the French version of the product datasheet.

Therefore, to promote the various language versions of a product datasheet, you first list the queries that could lead to the desired product datasheet, such as Large Plastic Box in English and Grande boîte de plastique in French. Then, you select the items to promote when an end user makes one of these queries, and use a family field and a language field to identify them as identical items in different languages.

As a result, when an end user queries Grande boîte de plastique, Coveo recognizes this query as a French query, and looks in the corresponding family of datasheet items for the French version to display as a featured result.

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

  • Depending on your organization creation date, the default behavior differs (see Organization ID and Other Information):

    • In organizations created after June 10, 2019, a featured result must match the search interface scope, facet selection, and other hidden or user-selected filters to be displayed.

    • In organizations created before June 10, 2019, featured results are displayed regardless of the selected filters (see matchAdvancedQuery Parameter). This means that, by default, in these organizations, featured results could appear at the top of search results from which they would otherwise be excluded.

One of your customers searches for Printer J249-MQ on your e-commerce search page. This query meets a featured result rule you have created, which is If query contains "J249-MQ", show item "J249-MQ Color Printer User Manual", so this item is displayed at the top of the search results. Then, the user selects Community Forum in the Resource Type facet to display only the community forum search results containing Printer J249-MQ. However, item J249-MQ Color Printer User Manual does not belong to this resource type, as it is a manufacturer technical document.

In an organization created before June 10, 2019, the user’s facet value selection would not affect the featured result rule, and item J249-MQ Color Printer User Manual would still be displayed, although it would not appear in the refined search results if it were a regular, non-featured result. In an organization created after June 10, 2019, however, the featured item would disappear following the facet value selection because it would no longer be considered relevant for the user.

To edit a featured result rule, you have two options:

  • Use the Edit a Featured Result Rule panel, which is identical to the Add a Featured Result Rule panel (see Add or Edit a Featured Result Rule).

  • Use the Edit a Featured Result JSON Rule panel, which allows you to modify a rule JSON configuration.

The latter is especially useful when you want to implement a rule that does not fit with the parameters available in the Edit a Featured Result Rule panel.

To edit a featured result JSON rule

  1. Access the “Featured Results” tab of a Pipeline.

  2. In the Featured Results tab of a query pipeline, click the rule you want to edit.

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

  4. In the Edit a Featured Result JSON Rule panel that appears, 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.

     {
     "condition": {
         "reference": {
         "reference": "3896e64f-2132-463a-81c8-26f2e9f89e0a"
         }
     },
     "defaultMatchOperator": {
         "contains": {},
         "is": {},
         "matches": {}
     },
     "includeInFacets": true,
     "isMigrated": true,
     "matchAdvancedQuery": true,
     "matchQuery": true,
     "name": "winterPromotion01",
     "predicates": [
         {
         "basicQueryExpression": "video game",
         "locale": {
             "all": {}
         }
         }
     ],
     "qplPredicates": [
         {
         "code": "string"
         }
     ],
     "targets": [
         {
         "uniqueId": "2228d0a698fd"
         },
         {
         "localizedContent": {
             "familyId": "112233",
             "locale": {
             "auto": {
                 "default": "en-US"
             }
             },
             "familyIdField": "@sfarticlenumber",
             "localeField": "@locale"
         }
         }
     ]
     }
    
  5. Click Save.

  1. Access the “Featured Results” tab of a Pipeline.

  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.

  4. The duplicated rule appears at the bottom of the list.

  1. Access the “Featured Results” tab of a Pipeline.

  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.

Organization Created Before June 10, 2019

  1. Access the “Featured Results” tab of a Pipeline.

  2. In the Featured Results tab, you can add or edit a featured result rule:

    1. Access the Add a Featured Result Rule dialog by clicking Add Rule, and then selecting Featured results rule.

    2. In the Add a Feature Result Rule dialog:

      Since you can decide the content your users first see when they access your search interface or do an empty query, you promote your most popular and general topic. Using the item URI, you make the topic appears on top of the search results list.

      when $query is `@uri` then top `@urihash="dmov5JaJrXDEW90Z"`

      By default, when a search is launched and the search box is empty, the @uri query is performed, returning all items. The same query is performed when a user accesses a Coveo search interface.

      1. Click Select an item.

        The Content Browser appears on the screen.

      2. In the Content Browser, search and then select the item you want to promote.

        The URI of the item appears in the Item URI box.

      3. Select an operator (Contains, Matches, or Is), and then enter an expression in the second box that will trigger the featured result rule previously entered if the condition you will establish next in step 4 is respected.

        Before the featured result rule is applied:

        • When you select the Is operator, the user query must be the exact expression you enter in the box.

        • (For advanced users) When you select the Matches operator, the user query must match the regular expression (regex) you enter in the 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 provide the following regex:

          ^$

        • When you select the Contains operator, the expression you enter in the box must be a part of the user query.

      4. Click Add Rule.

        • The promoted result rule is effective the moment it is saved.

        • For developers, you can also directly enter a rule that respects the Query Pipeline Language (QPL) syntax for featured results referred to as top results in the Developers documentation (see Top Results):

          1. In the Featured Results tab, click Add Rule, and then select Featured results with code.

          2. In the Add a Rule With Code dialog, in the form editor box, enter a top results rule (see Top - Query Pipeline Feature).

            If you write a top results rule query expression referencing a field other than the standard @urihash or @permanentid:

            • Ensure that this field is included in query responses (see the fieldsToInclude option of the ResultList Coveo JavaScript Search Framework component).

            • If it is possible for the values of this field to contain more than one term, use the == comparison operator (rather than =), and enclose the value to match between double quotes (e.g., @author=="John Doe").

            • If there is more than one field, use the AND operator to connect them (e.g., @sfid=="0170b00012l2WIBAA2" AND @commonlanguage==$context.lang).

          3. Click Add Rule.
        • The item you promote must be in your Coveo Cloud organization index.

  3. When you want the featured result to only be displayed when matching the search interface scope, facet selection, and other hidden or user-selected filters, set the matchAdvancedQuery parameter to true:

    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.

    A user is looking for a Coveo for Salesforce component, and a Coveo for Sitecore item (that is used in a featured result rule) is the first result returned. Since the related featured result rule is set to match the advanced query, if the user selects Coveo for Salesforce in the Product facet, they will no longer see the Coveo for Sitecore item in the search results.

    1. In the Featured Results tab, click the Actions icon (Icon-SourceActions) next to the rule you want to modify, and then select Edit code.

    2. In the Edit a Rule With Code dialog, add the following string next to your top query pipeline statement:

      with matchAdvancedQuery: true

      top \@urihash=”3eXEhu37oF4NiyM4”` with matchAdvancedQuery:true`

    3. Click Save.

  4. You can perform other actions on rules (see Adding and Managing Query Pipeline Rules and Rule Conditions From Tabs).

  5. You can link a condition to a rule (see Adding and Managing Query Pipeline Conditions).

    Adding featured result rules without at least a condition can have a negative impact on the search results relevance.

  6. On the search interface(s) for your Coveo Cloud organization, test your featured result rule to ensure that it improves search result relevance. Make adjustments when needed.

    You can use the Content Browser search interface to test your top result rules.

See Edit a Featured Result JSON Rule under Organization Created After June 10, 2019.

Required Privileges

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