Adding and Editing Coveo Machine Learning Event Recommendations Models in a Query Pipeline

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

This article applies only for Coveo Cloud organizations created prior to April 23, 2019 that did not go through the Coveo ML migration process. Other organizations create models directly from the Models page (see Create a Model).

You create and manage your Event Recommendations models from the Coveo Cloud administration console for a query pipeline defined in your Coveo Cloud 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.

Access the “Machine Learning” Tab of a Pipeline

  1. If not already done, log in to the Coveo Cloud platform as a member of a group with the required privileges in the target Coveo Cloud organization.

  2. In the navigation bar on the left, under Search, select Query Pipelines.

  3. On the Query Pipelines page:

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

    1. Create a query pipeline (see Create a Query Pipeline).

      Set a condition for the pipeline to only apply on the desired search hub.

    2. Double-click the pipeline you just created.

  4. In the Edit a Query Pipeline: [Name] page, select the Machine Learning tab.

Manage Event Recommendations Models

Members with the privilege to view query pipelines (i.e., the View all or the Custom access level on the Query Pipelines domain) can click View to review Coveo Machine Learning (Coveo ML) model configurations in read-only mode (see Privilege Management and Query Pipelines Domain).

  1. In the Machine Learning tab (see Access the “Machine Learning” tab of a Pipeline):

    • Create an Event Recommendations model.

      You need to create more than one recommendation 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).

      1. Ensure that view events and search action events are being pushed to Coveo Usage Analytics (Coveo UA) for your organization (see Coveo Machine Learning Event Recommendations Deployment Overview).

        When there are no view events or enough data to recommend an event, the Content Browser on which is applied the dedicated pipeline will return no results, and the recommendation component will be empty on an hosted search page.

        In a sandbox environment, chances are you will not actually get recommendations. You need to have visits on your page to recommend content relevant to the user visit history. The required data is collected each time a user visits a page containing the Page View Analytics component (see Pushing Coveo Usage Analytics View Events).

        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 you did not create a model yet, click Add Model in the center of the page.


        On the right-hand side of the page, click the Add Model drop-down menu, and then select Machine Learning model.


    • (For developers only) Create an Event Recommendations model with a Query Pipeline Language (QPL) statement :

      1. If you did not create a model yet, click Add Model with Code in the center of the page.

        Alternatively, on the right-hand side of the page, click the Add Model drop-down menu, and then select Machine Learning with code.

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

      3. Click Add Model.


    • Modify an existing model by double-clicking the model that you want to change or, by clicking the model row, and then in the Action bar, clicking Edit.

      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 Machine Learning Model Without Service Interruption).

  2. 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 Event recommendations.

    2. In the first input, enter a meaningful display Name for the model.

      The name appears in the Name column on the Models page.


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

  3. 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 between the following values: 1 week, 1 month, or 3 months. The default value is 3 months, meaning the last 90 days from today (see Training and Retraining).

      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 view events pushed to Coveo UA 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 view events that are pushed to Coveo UA 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 view event 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 an event recommendation model to an existing query pipeline, which is not recommended, can make search interfaces return no results if the model does not have recommendations to give for a given user query. You must thus 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, ideally the same that applies on the query pipeline containing the model.

      • 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. On the Conditions page, edit a condition (see Modify a Condition).

      3. Access again the Condition to be applied section of the new model.

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

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

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

  5. 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 Machine Learning Model Without Service Interruption).


  6. Back on 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 With Code panel.

      1. Select the model row.

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

      3. In the Edit a Model With Code 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.

  7. Verify if an event recommendation model with the same configuration already exists in your organization:

    On the Models page, if your new model is not listed under the Name column, it means that a model with the exact same configuration already exists.

    The model shown in the Models page depends on where the models sharing the same exact configuration are located:

    • When the models are in the same pipeline, the first one that was created is displayed.
    • When the models are in separate pipelines, the model that was created in the most recent pipeline is displayed.
  8. You can perform other actions on your Event Recommendations model (see Adding and Managing Query Pipeline Rules From Tabs).

Required Privileges

The following table indicates the required privileges to view or edits elements of the Query Pipelines page and associated panels (see Privilege Management and Privilege Reference).

Action Service - Privilege Required access level
View event recommendation models

Analytics - Analytics data

Analytics - Dimensions

Machine Learning - Models

Organization - Organization

Search - Query pipelines

Edit event recommendation models

Analytics - Analytics data

Analytics - Dimensions

Organization - Organization


Machine Learning - Models

Search - Query pipelines


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