Leverage Coveo Machine Learning

Coveo Machine Learning (Coveo ML) can dramatically improve relevance in your search solution by providing your users with AI-powered query suggestions and Automatic Relevance Tuning (ART).

This article explains how to leverage these functionalities in a Coveo-powered search interface.


The Coveo ML Content Recommendation (CR) and Dynamic Navigation Experience (DNE) features require a more complex setup. For more information, see:

Are you ready to enable machine learning?

To maximize relevance in your search solution, there are certain steps that you should follow before you deploy Coveo ML. These steps are illustrated in the following diagram:

Are you ready for machine learning? | Coveo
  1. Your Coveo organization index must contain the items that need to be searchable by its intended audiences. If you neglect this step, it can negatively affect the search experience and interfere with the way that Coveo ML models use data to optimize relevance.

  2. The search solution must be analyzed to determine whether a specific area needs improvement. 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.

  3. The dashboards, explorers, and reports should provide key insights on whether a search solution needs improvement. This information will help you identify areas in which users aren’t getting what they need and determine whether Coveo ML could help solve these issues.

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

  5. You’re ready to create your Coveo ML models.

Create your Coveo ML models

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

Basic configuration

You should typically use the default settings when creating your QS, ART, and DNE models. You must also ensure that enough UA 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 on a single website. You’re currently routing all search and query suggestion requests to the same Default query pipeline.

Once you have gathered enough UA data to start leveraging Coveo ML, you duplicate the Default query pipeline. In the resulting Default Copy query pipeline, you create ART and QS models. You then set up an A/B test between the two query pipelines, routing 30% of the traffic to Default Copy.

Over the following weeks, you monitor the dashboard to see how your ML models are performing. They appear to have a positive impact on the relevance of your search solution, so you decide to apply your new models to the Default query pipeline. You disable the A/B test and delete the Default Copy query pipeline.


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

However, we recommend that you avoid using custom model parameters unless you know what you’re doing and have a good reason for using them. You should only use these advanced options to handle highly specific use cases.

Configure your search interface

A search interface that leverages the Coveo Atomic library will log search and click events automatically. This means that you can take advantage of the Coveo ML ART and QS features right away, assuming that the corresponding models are active.

However, to power a CR model, you must send view events for the target items.

Coveo ML models then train on recorded UA data. After training, an ART model will tune the relevance of the results presented in an atomic-result-list and a QS model will provide contextually-relevant query suggestions as your users type in an atomic-search-box.

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

    The Atomic library supports localization and includes translations into several languages out of the box.

  • The search hub plays an important role in the output of your Coveo ML models.

    We recommend that you enforce the search hub through the search token or API key.

    You should set this to a unique value for each of your search interfaces. For example, your community and internal search interfaces should each have a different searchHub value.

  • 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 when the query results are sorted using criteria other than relevance (such as by date or field).


The following search interface benefits from the Coveo ML QS and ART features.

<!DOCTYPE html>
    <script type="module" src="https://static.cloud.coveo.com/atomic/v2/atomic.esm.js"></script>
    <link rel="stylesheet" href="https://static.cloud.coveo.com/atomic/v2/themes/coveo.css"/>
      (async () => {
        await customElements.whenDefined("atomic-search-interface");
        const searchInterface = document.querySelector("#search");

        await searchInterface.initialize({
          accessToken: '<ACCESS_TOKEN>',
          organizationId: '<ORGANIZATION_ID>',
          organizationEndpoints: await searchInterface.getOrganizationEndpoints('<ORGANIZATION_ID>')

    <atomic-search-interface id="search">


        <atomic-layout-section section="search">

        <atomic-layout-section section="main">
          <atomic-layout-section section="results">
            <atomic-result-list display="grid">
              <!-- ... -->
          <!-- ... -->



As you can see in the following screen capture, the search box displays query suggestions, and the items in the result list are relevant thanks to Coveo ML ART:

A search interface that leverages Coveo ML | Coveo

Provide personalized Coveo ML output

Coveo ML models can use context to learn from user behavior and improve their relevance. The CR feature in particular uses custom context to provide more personalized output.

You can add this custom context by modifying the requests sent from a search interface that leverages the Atomic library. You can also provide custom context for recommendations by accessing the Coveo Headless library through Atomic.

  • On an ecommerce site, you want to promote certain products based on the country in which the user resides. You retrieve the country from each user’s IP address and send this information as custom context.

  • On a customer support site, you have access to the list of products owned by authenticated 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 Common pitfalls section lists some of the most frequently made mistakes in a search project and explains how to avoid them.