Leveraging Coveo Machine Learning

Coveo Machine Learning (Coveo ML) can dramatically improve relevance in your search solution by providing your end users with AI-powered Query Suggestions (QS) and Automatic Relevance Tuning (ART) (see Coveo Machine Learning).

This article explains how to leverage these functionalities in a Coveo JavaScript Search Framework interface.

Are You Ready to Enable Machine Learning?

The following diagram illustrates the preliminary steps you should follow before deploying Coveo ML in your search solution to maximize its relevance.

Are You Ready for Machine Learning
  1. Your Coveo organization index must contain the items that need to be searchable by its intended audiences. Neglecting this step can negatively affect the search experience and interfere with the way Coveo ML models use data to optimize relevance (see Locating and Indexing Content).

  2. The search solution must be analyzed to determine if a specific area needs to be improved. At this point, your search interfaces need to be properly designed and must accurately log usage analytics events. You specifically need to ensure that meaningful dashboards, explorers, and reports have been configured (see Examining Usage Analytics Data).

  3. The dashboards, explorers, and reports should provide key insights on where a search solution might need improvements. This information should help you identify areas where end users aren’t getting what they need, and determine whether Coveo ML could eventually help solving those issues (see Examining Usage Analytics Data and Coveo Machine Learning Features).

  4. You must ensure that sufficient data is available for Coveo ML models to provide relevance in your search experience. Since each model type uses and processes data in a distinct way, your Coveo organization must collect the appropriate inputs. At this point, the more quality data a model can learn from, the more effective it will get.

  5. You’re ready to leverage Coveo ML. You can proceed to the next section in this article (see Create Your Coveo ML Models).

Create Your Coveo ML Models

You must create your Coveo ML models using the Models (platform-eu | platform-au) page of the Coveo Administration Console to be able to take advantage of the Coveo ML QS, ART, and DNE features in a properly configured search interface.

To create your models from the Models page, see Creating a Model.

Coveo ML Models Basic Configuration

Usually, you should use the default settings when creating your QS, ART, and DNE models. Ensure that sufficient usage analytics data has been recorded in your Coveo organization before creating your models. A newly created model should become active within an hour or so.


Your Coveo organization is powering search in a single website. As such, you’re routing all search and query suggestions requests to the same Default query pipeline (see Basic Query Pipeline Setup).

You have gathered enough usage analytics data to start leveraging Coveo ML. You duplicate the Default query pipeline, and create a QS model and an ART model in the resulting Copy of Default query pipeline.

You then set up an A/B test between those two query pipelines, routing 30% of traffic to Copy of Default (see Manage A/B Tests). In the following weeks, you monitor usage analytics dashboard to see how your ML models are performing (see Analyze the Performance of Pipeline A Vs Pipeline B). As they appear to have a positive impact on the relevance of your search solution, you decide to apply your new models to the Default query pipeline. You then disable the A/B test and delete the Copy of Default query pipeline.


In addition to the basic configuration options which are available when creating or editing a Coveo ML model from the Coveo Administration Console, several custom model parameters exist (see Custom Model Parameters).

Those advanced options should only be used to deal with highly specific use cases. Unless you know what you’re doing and have a good reason for doing so, you should typically avoid using custom model parameters.

Configure Your Search Interface

A JavaScript Search Framework interface simply needs to include the Analytics, Searchbox, and ResultList components to be able to take advantage of the Coveo ML QS and ART features, assuming that corresponding models are active (see Create Your Coveo ML Models).

The Analytics component takes care of automatically sending search and click events to the Usage Analytics Write API when an end user submits a query or opens a query result, respectively. Coveo ML models then train on recorded usage analytics data, and eventually yield contextually relevant query suggestions to your end users as they’re typing in the Searchbox, and ART which is leveraged by the ResultList.


A standalone search box doesn’t require an Analytics component to benefit from the Coveo ML QS feature (see Create a Standalone Search Box).

  • Coveo ML models only yield output in the language of the current end-user.

    By default, a JavaScript Search Framework interface uses the English language. If you use culture files to localize your search interface, the corresponding language will be used (see Change the Language of Your Search Interface).

  • The searchHub option of the Analytics component also plays an important role in the output of your Coveo ML models.

    You should set this option to a unique value for each of your search interfaces (e.g., the Analytics component in your community search interface should have a different searchHub option value than the one in your internal search interface).

  • When Tab components are present in a search interface, they also play an important role in the output of your Coveo ML models.

    A Coveo ML model filters its output according to the current searchHub (i.e., origin level 1) and tab (i.e., origin level 2) combination (e.g., if the end user has selected a Tab whose id is Video in a search interface whose searchHub is Community, the ML models will only yield output learned from previous end-user interactions in the Community/Video context).

  • The Coveo ML ART feature only works when query results are sorted by relevance.

    The ART feature increases the score values of the most contextually relevant query result items. However, score values aren’t computed at all when query results are being sorted by other criteria than relevance (e.g., date, field, etc.).

  • If you create your own result templates, remember to use the ResultLink component to output clickable links for each query result item.

    The ResultLink component is responsible for forwarding click usage analytics event data to the Analytics component. Click usage analytics events are essential for training your Coveo ML models.


The following bare-bones search interface can still benefit from the Coveo ML QS and ART features.

<!DOCTYPE html>
  <link rel="stylesheet" href="https://static.cloud.coveo.com/searchui/v2.5395/css/CoveoFullSearch.css"/>
  <script src="https://static.cloud.coveo.com/searchui/v2.5395/js/CoveoJsSearch.Lazy.min.js"></script>
  <script src="https://static.cloud.coveo.com/searchui/v2.5395/js/templates/templates.js"></script>
    document.addEventListener('DOMContentLoaded', () => {
<body id="search" class="CoveoSearchInterface">
  <div class="CoveoAnalytics">
  <div class="CoveoPromotedResultsBadge" data-show-badge-for-recommended-results="true"></div>
  <div class="coveo-tab-section">
    <a class="CoveoTab" data-id="All" data-caption="All"></a>
  <div class="coveo-search-section">
    <div class="CoveoSearchbox"></div>
  <div class="coveo-main-section">
    <div class="coveo-results-column">
      <div class="CoveoResultList" data-layout="list"></div>

As you can see in the following screen capture, the search box is displaying query suggestions, and query result items promoted by the Coveo ML ART feature are identified in the result list thanks to the PromotedResultsBadge component.

A bare-bone search interface leveraging Coveo ML

Prior versions of the Coveo JavaScript Search Framework require that the enableOmnibox and enableQuerySuggestAddon options be explicitly set to true on the Searchbox component to enable QS.

Those options are now both true by default.

Provide Personalized Coveo ML Output

In a Coveo JavaScript Search Framework interface, you can use the PipelineContext component to add custom context information to each query, partial query, and usage analytics event sent from that search interface (see Send Custom Context Information). Your Coveo ML models can learn from this information to yield more personalized output (see About Custom Context).

  • On a commerce site, you want to promote certain products based on the country the end user resides in. You retrieve the country from the IP address of each end user and send this information as custom context.

  • On a customer support site, you have access to the list of products owned by authenticated end users. You send this information as custom context, allowing your Coveo ML models to further promote query suggestions and result items related to those products.

What’s Next?

The next section in this guide lists some of the most frequently made mistakes in a search project, and explains how to avoid them (see Common Pitfalls).

What's next for me?