Adding Coveo Machine Learning Recommendations Models

Coveo™ Machine Learning (Coveo ML) is a service that leverages usage analytics data (see Coveo Machine Learning). The Recommendation feature analyzes your websites page views and search action events for all users to predict and propose the most relevant content for the current user in the current session (see Event Recommendations Feature and Coveo Machine Learning Event Recommendations Deployment Overview).

You create and manage your Recommendation models from the Coveo Cloud administration console for a query pipeline defined in your Coveo Organization. A model learns from a usage analytics data set recorded over a given period, and is retrained at a selectable frequency to maintain its freshness (see Coveo Machine Learning Models). The default values for available parameters are typically appropriate in most cases, but the following procedure details why or when you may want to change them.

Add a Recommendations Model

  1. Ensure that page view and search action events are being pushed to the Coveo Cloud usage analytics service for your organization (see Coveo Machine Learning Event Recommendations Deployment Overview).

    If no usage analytics data is available, there will be no recommendations. When you just start gathering data, recommendations will progressively improve as more data becomes available each time the model is retrained (see Training and Retraining).

  2. If not already done, log in to your Coveo organization using account member Admin or Relevance Analyst user role account.

  3. In the administration tool navigation bar on the left, under Search Optimization, select Query Pipelines.

  4. In the Query Pipelines page, create or edit the query pipeline for which you want to manage recommendations (see Managing Query Pipelines).

    Use one dedicated pipeline for each of your Recommendations model. The pipeline should contain no other Coveo ML models or other feature rules that can interfere with the recommendation model.

  5. In the Machine Learning tab:

    If the Machine Learning tab is not visible, contact Coveo Support to request to enable Coveo ML in your Coveo Cloud organization.

    • Create a recommendations model by clicking Add Model.

      You need to create more than one Recommendations model only when you want to be able to include recommendation windows for different content types (see the note in Coveo Machine Learning Event Recommendations Deployment Overview).


    • (For developers only) Create a Recommendations model in Query Pipeline Language (QPL):

      You can directly enter a configuration rule that respects the Query Pipeline Language (QPL) syntax for a Recommendations model.

      1. Click Add Model with Code.

      2. In the form editor box that appears, enter a Recommendations (recommendation) model configuration rule (see REST Search API Models).

      3. Click Save.


    • Modify an existing model by clicking the model to change or, clicking the Actions icon (Icon-SourceActions), and then selecting Edit model.

      Currently, when you edit an existing model, the Recommendation service is interrupted for about one hour while the model is trained with the new configuration. The recommended work around is to rather duplicate and customize the model, and make the new model effective when it is ready (see Editing a Coveo Machine Learning Model Without Service Interruption).

  6. In the Add a Machine Learning Model or Edit a Machine Learning Model panel, in the left section:

    1. (In the Add a Machine Learning Model panel only) Click the Select model type drop-down menu, and then select Give recommendations.

    2. In the User note input, enter useful information such as the creation or edition date and the purpose of the model.

      John Smith - 2016-09-17 - Promote new products and classes to our online help users

  7. In the Add a Machine Learning Model or Edit a Machine Learning Model panel, in the right section, evaluate if you need to change some of the default values:

    1. In the Training set section:

      1. In the Update frequency drop-down menu, select the time interval at which the model is retrained between the following values: Daily, Weekly, or Monthly. The default value is Weekly for the default 3 months Data period (see Training and Retraining).

      2. In the Data period drop-down menu, select the usage analytics data time interval on which the model will be based. Available data periods depend on the Update frequency you select (see Training and Retraining). The default value is 3 months, meaning the last 90 days from today.

      3. When you want to train the recommendations model with usage analytics data from a specific search hub, consider adding a hub filter:

        If you need to create more than one recommendations model (each in a dedicated query pipeline), you should add a data filter to feed only the data appropriate to each pipeline.

        1. Under Train on events, select the Specific radio button.

        2. Click Origin 1 (Page/Interface).

        3. Select the Is operator.

        4. In the Enter filter value input, select or type the name for your search hub.

        5. Click Add Filter.

      4. When you want to train the recommendations model with usage analytics data from a specific geographic origin, consider creating Country and or Region filters.

    2. In the Recommended items section, under Recommended item types, select the Specific radio button and then add a View Content Type filter when you want the model to return recommendations of only one or a few specific content types. Leave the All radio button selected (default value) to return any type of content.

      The page view events pushed to the usage analytics service for your organization include content of various types such as Article, Application, Download, and Course. You want to use this model to recommend only relevant downloads. You select Download.

      • The page view events that are pushed to the usage analytics service for your organization must contain appropriate contentType values (see Coveo Machine Learning Recommendation Content Types).

      • The View Content Type option does not behave like the other filters. All page view content types and search events are analyzed to create the model, but only pages of the specified content type(s) are recommended.

    3. In the Condition to be applied section, add a condition:

      Adding a recommendations model to a query pipeline can make search interfaces return no results if the model does not have recommendations to give for a given user query. It is thus strongly recommended to set a condition for the model to be used.

      • If you added one or more data filters in a previous step, you generally want to duplicate your data filter condition as a model condition so that the recommendations are returned only when this condition is met.

      • The condition is override for a JavaScript Search Recommendations component when the pipeline in which this model is hosted is hardcoded in its data-pipeline attribute.

      In the list of available conditions, select a condition.

      • At the bottom-right of the list, click the left and right arrow icons, or a page number to navigate through pages.

      • At the bottom-left of the list, select 10 or 100. By default, the table shows 10 conditions per page.


      Create a new condition by clicking Add Condition (see Create a Condition).


      Edit an existing condition:

      1. Click Manage Conditions.

        You lose all unsaved changes if you clicked Confirm in the Are You Sure confirmation prompt that appears. It is thus recommended to Save the model before creating a condition.

      2. In the Conditions page, edit a condition (see Modify a Condition).

      3. Access again the Condition to be applied section of a new model or the model you edited.

      4. In the list of available conditions, select the condition you edited.

  8. At the bottom of the Add a Machine Learning Model or Edit a Machine Learning model panel, click Add or Save.

    The instructions to create or modify the model are sent to the Coveo ML service.

  9. When you edit a model, in the Are You Sure? dialog box, click Confirm only when it is acceptable for you to get a Recommendation service interruption, which is very noticeable for end-users that are expecting suggestions to appear below the search box.

    Otherwise, click Cancel and use the other method (see Editing a Coveo Machine Learning Model Without Service Interruption).


  10. Back in the Machine Learning tab of your pipeline page:

    1. On the model row, in the Status column, the value is most probably In progress.

      The value will change to Ready when the model creation or modification is completed, typically within 30 minutes, depending on the amount of usage analytics data to process. The model can return recommendations only when its status is Ready.

    2. (Optionally) Edit the model code:

      In special cases, the Coveo Support team may propose you to make advanced model configuration changes using the Edit a Model in QPL panel.

      1. Select the model row.

      2. In the Action bar, click More, and then select Edit QPL.

      3. In the Edit a Model in QPL panel, modify the model code as was proposed by Coveo Support.

        Do not change the model code unless you are told by Coveo.

      4. Click Save.

Who Can Perform the Page Actions

The required roles are:

  • Administrator


  • Relevance Analyst

What’s Next?

Include a Coveo JavaScript Search Recommendation component in your website pages where you want to show recommendations from this model (see Coveo Machine Learning Event Recommendations Deployment Overview).