---
title: Create and manage an Automatic Relevance Tuning (ART) model
slug: '3397'
canonical_url: https://docs.coveo.com/en/3397/
collection: leverage-machine-learning
source_format: adoc
---
# Create and manage an Automatic Relevance Tuning (ART) model

[Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [Automatic Relevance Tuning (ART)](https://docs.coveo.com/en/1013/) [models](https://docs.coveo.com/en/1012/) improve the relevance of search results.

ART learns from search and click [events](https://docs.coveo.com/en/260/).
If you're using an ART model [in a Coveo for Commerce implementation](https://docs.coveo.com/en/o3m90077/), it can also learn from commerce-specific user actions such as [cart](https://docs.coveo.com/en/o1n93466/) and [purchase](https://docs.coveo.com/en/o1n93059/) events.
However, even in a Coveo for Commerce implementation, ART models can't learn from commerce events alone.

To take advantage of [Coveo ML](https://docs.coveo.com/en/188/) [ART](https://docs.coveo.com/en/1013/), [members](https://docs.coveo.com/en/2869/) with the [required privileges](https://docs.coveo.com/en/3397#required-privileges) must first create ART [models](https://docs.coveo.com/en/1012/).

## Prerequisites

Before creating an ART model, your [Coveo organization](https://docs.coveo.com/en/185/) must collect enough [data](https://docs.coveo.com/en/259/).
To start providing recommendations, the model needs:

* At least 100 search and click events (see [Sending the required usage analytics event data](https://docs.coveo.com/en/1858#sending-the-required-usage-analytics-event-data)).

> **Note**
>
> If fewer than 100 search and click events have been logged, ART models don't boost the ranking weight of any items.
> However, you can [change this threshold if needed](https://docs.coveo.com/en/2935/).

* To be part of a [search interface](https://docs.coveo.com/en/2741/) that records at least 55 [visits](https://docs.coveo.com/en/271/) per day.
Each visit must contain at least one [user](https://docs.coveo.com/en/250/) [query](https://docs.coveo.com/en/231/) that has been followed by a click for a specific language.

> **Note**
>
> You can train a new model by [linking queries to results](https://docs.coveo.com/en/1858#training-art-models-by-linking-queries-to-results).

To analyze whether the search interface in which you want to integrate the ART model produces enough data, see [Troubleshoot ART models](https://docs.coveo.com/en/1858/).

## Create an ART model

. On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page of the [Coveo Administration Console](https://docs.coveo.com/en/183/), click **Add model**, and then click the **Automatic Relevance Tuning** card.

. Click **Next**.

. (Optional) In the [**Learning interval**](#learning-interval-section) section, you can change the default and recommended values for both **Data period** and **Building frequency**.

. Click **Next**.

. (Optional) If you want your ART model to automatically consider [cart](https://docs.coveo.com/en/o1n93466/) and [purchase](https://docs.coveo.com/en/o1n93059/) event data, activate the **Include commerce events** option.

> **Leading practice**
>
> Activate this option in [Coveo for Commerce implementations](https://docs.coveo.com/en/o3m90077/), such as when configuring an ART model for [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187/).
> 
> By default, ART models only consider the most-clicked products for a given query, from a specific search interface and tab combination.
> With this option enabled, they also consider all "add to cart" and "purchase" events that occur within a particular site (or application).
> 
> However, ART models can't learn from commerce events alone.
> These events can only help reinforce popularity trends and boost product rankings.
> ART models always require search and click events.

. (Optional) In the **Apply filters on dataset** section, you can add filters to refine the data that the model uses to make its recommendations.
By narrowing down the dataset that a model uses, you can better customize relevancy for specific user groups and use cases.
You can apply filters on all events, or on every event that belongs to a specific category, such as search, click, view, or custom events.

**Example**

Your Community search and Agent search have very specific vocabulary.
You don't want them to influence one another in the ART model learning process, so you add a filter on the **Origin 1 (Page/Hub)** dimension.

This allows your model to learn independently from the actions performed on the different search interfaces.

> **Tip**
>
> The **Data volume preview** section shows the impact of filters on the data that's available to train the model.
> This section includes data gathered only during the last seven days and doesn't consider the selections from the **Learning interval** section.

.. In the **Select a dimension** dropdown menu, select the dimension on which you want to base the learning of the model.

.. In the **Select an operator** dropdown menu, select the appropriate operator.

.. In the **Select value(s)** dropdown menu, add, type, or select the appropriate value.

.. You can optionally add other filters by clicking **Add**.

> **Note**
>
> When configuring an ART model that doesn't serve a commerce interface, don't configure filters based on **Custom** dimensions as ART models don't use custom events in their learning datasets. Doing so would result in the model not applying any filtering.

. Click **Next**.

. In the **Name your model** input, enter a meaningful display name for the model.

. (Optional) Use the **Project** selector to associate your model with one or more [projects](https://docs.coveo.com/en/n7ef0517/).

. Click **Start building**.

> **Note**
>
> On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page, under the **Status** column, in the model row, the value is most probably **Inactive**.
> 
> The model value will change to **Active** when the model creation is complete (typically within 30 minutes, depending on the amount of usage analytics data to process).
> The model can only return recommendations when its status is **Active**.
> 
> For more information on Coveo ML model statuses, see the [**Status** column reference](#status-column).

. (Optional) Configure [advanced settings](#advanced-configuration) for your model.

. [Associate the model with a pipeline](https://docs.coveo.com/en/l1ca1038/) to use the [model](https://docs.coveo.com/en/1012/) in a [search interface](https://docs.coveo.com/en/2741/) and [test your model](https://docs.coveo.com/en/mc2g0297#test-your-art-model) to make sure it behaves as expected.

> **Important**
>
> Make sure to follow the [model association leading practices](https://docs.coveo.com/en/l1ca1038#leading-practices) before associating your model with your production query pipeline.

## Advanced configuration

You can configure advanced settings for your [model](https://docs.coveo.com/en/1012/) to suit specific use cases.

Some advanced settings are available from the [model](https://docs.coveo.com/en/1012/) options in the [Administration Console](https://docs.coveo.com/en/183/), while others are only available through JSON configuration parameters.

> **Notes**
>
> * Additional model configurations can be specified through the [Advanced Model Configuration API](https://docs.coveo.com/en/l3od9093/).
> 
> * You can also use the [`mlParameters` query parameter](https://docs.coveo.com/en/13#operation/searchUsingPost-mlParameters) to adjust the way your Coveo ML models are used at query time.

To specify advanced settings

. On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page, click the model for which you want to specify advanced settings.

. Do one of the following:

* To specify an advanced setting using an [Administration Console](https://docs.coveo.com/en/183/) [model](https://docs.coveo.com/en/1012/) option:

.. Click **Edit** in the Action bar.

.. Click the **Advanced** tab, and then in the **Advanced** page left menu, select the setting to configure:

** [Suggestion filters](#suggestion-filters)
** [Test configuration mode](#test-configuration-mode)

* To specify an advanced setting using a JSON parameter:

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

.. Enter the advanced parameter configuration in the JSON's `extraConfig` object:

** [`automaticContextDiscovery`](#automaticcontextdiscovery-boolean)
** [`commerceSupport`](#commercesupport-object)
** [`filterFields`](#filterfields-list-of-strings)
** [`recommendProductGroup`](#recommendproductgroup-boolean)
** [`userContextFields`](#usercontextfields-list-of-strings)

[start=3]
. Click **Save**.

## Manage an ART model

You can edit using the [model options](#edit-an-art-model) or [JSON](#edit-an-art-model-json-configuration), [delete](#delete-an-art-model), or [review information](#review-model-information) for your [model](https://docs.coveo.com/en/1012/).

### Edit an ART model

. On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page, click the model you want to edit, and then click **Edit** in the Action bar.

. On the subpage that opens, select the **Configuration** tab.

. Under **Name**, you can optionally edit the model's display name.

. (Optional) Use the **Project** selector to associate your model with one or more [projects](https://docs.coveo.com/en/n7ef0517/).

. (Optional) Depending on whether you want your ART model to automatically consider [cart](https://docs.coveo.com/en/o1n93466/) and [purchase](https://docs.coveo.com/en/o1n93059/) event data, you can activate or deactivate the **Include commerce events** option.

> **Leading practice**
>
> Activate this option in [Coveo for Commerce implementations](https://docs.coveo.com/en/o3m90077/), such as when configuring an ART model for [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187/).
> 
> By default, ART models only consider the most-clicked products for a given query, from a specific search interface and tab combination.
> With this option enabled, they also consider all "add to cart" and "purchase" events that occur within a particular site (or application).
> 
> However, ART models can't learn from commerce events alone.
> These events can only help reinforce popularity trends and boost product rankings.
> ART models always require search and click events.

. (Optional) In the [**Learning interval**](#learning-interval-section) section, you can change the default and recommended values for both **Data period** and **Building frequency**.

. (Optional) In the **Apply filters on dataset** section, you can add filters to refine the data that the model uses to make its recommendations.
By narrowing down the dataset that a model uses, you can better customize relevancy for specific user groups and use cases.
You can apply filters on all events, or on every event that belongs to a specific category, such as search, click, view, or custom events.

**Example**

Your Community search and Agent search have very specific vocabulary.
You don't want them to influence one another in the ART model learning process, so you add a filter on the **Origin 1 (Page/Hub)** dimension.

This allows your model to learn independently from the actions performed on the different search interfaces.

> **Tip**
>
> The **Data volume preview** section shows the impact of filters on the data that's available to train the model.
> This section includes data gathered only during the last seven days and doesn't consider the selections from the **Learning interval** section.

.. In the **Select a dimension** dropdown menu, select the dimension on which you want to base the learning of the model.

.. In the **Select an operator** dropdown menu, select the appropriate operator.

.. In the **Select value(s)** dropdown menu, add, type, or select the appropriate value.

.. You can optionally add other filters by clicking **Add**.

> **Note**
>
> When configuring an ART model that doesn't serve a commerce interface, don't configure filters based on **Custom** dimensions as ART models don't use custom events in their learning datasets. Doing so would result in the model not applying any filtering.

. (Optional) Configure [advanced settings](#advanced-configuration) for your model.

. Click **Save**.

> **Note**
>
> Some configuration changes initiate an automatic model rebuild when you save the model.
> The [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page shows your model's current **Status**.
> Model settings take effect only when its status is **Active**.
> 
> For more information on Coveo ML model statuses, see the [**Status** column reference](#status-column).

. [Associate the model with a pipeline](https://docs.coveo.com/en/l1ca1038/) to use the [model](https://docs.coveo.com/en/1012/) in a [search interface](https://docs.coveo.com/en/2741/) and [test your model](https://docs.coveo.com/en/mc2g0297#test-your-art-model) to make sure it behaves as expected.

> **Important**
>
> Make sure to follow the [model association leading practices](https://docs.coveo.com/en/l1ca1038#leading-practices) before associating your model with your production query pipeline.

### Edit an ART model JSON configuration

. Access the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page.

. Click the desired model, and then click **More** > **Edit JSON** in the Action bar.

. In the **Edit a Model JSON Configuration** panel that appears, modify the existing model configuration:


```json
{
  "modelDisplayName": "<MODEL_DISPLAY_NAME>",
  "exportPeriod": "<EXPORT_PERIOD>",
  "intervalTime": <INTERVAL_TIME>,
  "intervalUnit": "<INTERVAL_UNIT>",
  "commonFilter": "<COMMON_FILTER>",
  "customEventFilter": "<CUSTOM_EVENT_FILTER>",
  "exportOffset": "<EXPORT_OFF_SET>",
  "searchEventFilter": "<SEARCH_EVENT_FILTER>",
  "viewEventFilter": "<VIEW_EVENT_FILTER>",
  "extraConfig": [<ADVANCED_ML_PARAMETERS>],
}
```


Where:


* `modelDisplayName` (string) is the name of the model appearing on the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page.

* `exportPeriod` (ISO-8601 string, _required_) is the period defining the age of the [Coveo Analytics data](https://docs.coveo.com/en/259/) used to build the model.
Must be in the ISO8601 period format (that is, `PyYmMwWdDThHmMsS`).

> **Note**
>
> Unless an [`exportOffset`](https://docs.coveo.com/en/3397#exportoffset) is specified, the `exportPeriod` uses the moment when the model was generated as a base.
* `intervalTime` (integer, _required_) is the number of `intervalUnit` (that is, `DAY`, `WEEK`, or `MONTH`) between each update of the model.
Must be between `1` and `30` inclusively.

* `intervalUnit` (string enum, _required_) is the duration unit of the interval between each update of the model.
See `intervalTime`.
Accepted values are: `DAY`, `WEEK`, and `MONTH`.

* `commonFilter` (string) is the filter to apply to the common event dimensions (shared by all event types) in the export. Multiple filter parameters are joined with the `AND` operator.

* `customEventFilter` (string) is the filter to apply to the custom event dimensions in the export. Multiple filter parameters are joined with the `AND` operator.

* [[exportoffset]] `exportOffset` (ISO-8601 string) is the offset of the usage analytics data used to build the model.
Must be in the ISO8601 period format (that is, `PyYmMwWdDThHmMsS`).
The default value is `PT0S`, meaning that all events are considered when building a model (the `exportPeriod` is based on the moment the model was generated).

**Example**

You want to ignore events that occur on the current day, so you set the `exportOffset` value to `P1D`.

* `searchEventFilter` (string) is the filter to apply to the click and search event dimensions in the export. Multiple filter parameters are joined with the `AND` operator.

* `viewEventFilter` (string) is the filter to apply to the view event dimensions (shared by all event types) in the export. Multiple filter parameters are joined with the `AND` operator.

* `extraConfig` (array of string) are additional [advanced parameters](#advanced-json-model-parameters) used to tailor the model to your use case.

. Click **Save** to apply your changes.

### Delete an ART model

> **Note**
>
> If the model is associated with a query pipeline, make sure to dissociate the model from the query pipeline after deleting it.

. On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page, click the ML model that you want to delete, and then click **More** > **Delete** in the Action bar.

. In the panel that appears, click **Delete**.

### Review model information

On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page, click the desired model, and then click **View** in the Action bar.
For more information, see [Reviewing model information](https://docs.coveo.com/en/1894/).

## Reference

### ART models reference

Default number of recommended results: 5

> **Note**
>
> ART recommends the 5 best learned search results, but may recommend fewer than 5 when:
> 
> * The query isn't very frequent, and less than 5 items were learned for that query.
> 
> * Some recommendations are secured and not accessible to the user performing the query.
> 
> * Some recommendations are filtered out because they don't match filters such as the current facet selections.
> [[art1]]

#### Facts

* Following an empty query, ART returns the most clicked items during the [data period](#learning-interval-section) of the model.

* ART can inject items that wouldn't normally be included in search results because they were learned to be relevant even if they don't contain some or all of the searched [keywords](https://docs.coveo.com/en/2738/).
This is one of the key ART benefits as a user can find the most useful [items](https://docs.coveo.com/en/210/) without having to type the right keywords or the specific synonym contained these items.
This is the default behavior (the [Match the Query](https://docs.coveo.com/en/l1ca1038#match-the-query) parameter default value is `false`).

* ART currently ignores all special characters or operators in the user entered query to only keep the keywords and therefore ignores the special behavior described in [Using Special Characters in Queries](https://docs.coveo.com/en/2744/) or [Search Prefixes and Operators](https://docs.coveo.com/en/1814/).

* This ART behavior may lead to unexpected search results when users want to take advantage of more advanced [query syntax](https://docs.coveo.com/en/181/).

**Example**

A user is searching for items containing a specific phrase by entering the phrase enclosed in double quotes (see [Searching for a phrase](https://docs.coveo.com/en/1686/)) and no items contain the phrase.
The user would expect to get no search results, but ART can inject items that were clicked for similar queries made of one or some of the searched keywords (not in a phrase search).

### Advanced model options

You can use the following options when [configuring advanced settings](#advanced-configuration) for your [model](https://docs.coveo.com/en/1012/).

#### Suggestion filters

Use the **Suggestion filters** advanced setting to set the [Coveo Analytics](https://docs.coveo.com/en/182/) dimensions to be used as filters for potential suggestions.

The [model](https://docs.coveo.com/en/1012/) filters the suggestions so that only the interaction data from events that include the specified dimensions are considered.

By default, the **Search hub** and **Tab** dimensions are selected.
This means that for a [query](https://docs.coveo.com/en/231/) that originates from a specific tab in a [search hub](https://docs.coveo.com/en/1342/), only interactions recorded in the same [search hub](https://docs.coveo.com/en/1342/) tab will be used by the [model](https://docs.coveo.com/en/1012/).

**Example**

Given the default values of **Search hub** and **tab**, and the following implementation:

* Two **Search hub** values: `partnerHub` and `techSupportHub`

* Four **Tab** values: `all`, `documentation`, `training`, and `community`

A total of eight possible filters will be created ( `partnerHub`/`all`, `techSupportHub`/`all`, `partnerHub`/`documentation`, etc.).
This means that if a query originates from `partnerHub`/`all`, only interactions recorded in `partnerHub`/`all` will be used by the [model](https://docs.coveo.com/en/1012/) to make suggestions for that query.

You can set this option to use the recommended **Search hub** and **Tab** dimensions (default), to not use filters at all, or to use custom filters based on dimensions of your choice.

To configure the suggestion filters

. On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page, click the model that you want to modify, and then click **Edit** in the Action bar.

. On the subpage that opens, select the **Advanced** tab.

. In the left menu of the **Advanced** tab, select **Suggestion filters**.

. Choose one of the following options:

** **Search hub and Tab** (default): The model uses the **Search hub** and **Tab** dimensions as filters for suggestions.

** **No dimension filters**: The model doesn't use any filters for suggestions.
This provides the same relevance across all search hubs that use the model.
It's useful when your model serves different search hubs in which the same source items are available.

** **Custom filters**: The model uses the dimensions that you select as filters for suggestions.

.. **Optionally**, select one or both of the **Search hub** and **Tab** filters.

.. Under **Other dimensions**, select the dimensions you want to use to filter the model suggestions (for example, `country` and `language`).

> **Important**
>
> If you set a dimension other than the two default ones (**Search Hub** and **Tab**), you must also add the dimension at query time using the `filters` [mlParameter](https://docs.coveo.com/en/13#operation/searchUsingPost-mlParameters).

![Custom filters configuration](https://docs.coveo.com/en/assets/images/leverage-machine-learning/ml-custom-dimension-filters.png)

. Click **Save**.

#### Test configuration mode

> **Note**
>
> The **Test configuration mode** advanced option is available only for sandbox organizations.

[Sandbox organizations](https://docs.coveo.com/en/2959#sandbox-organization) typically lack the amount of usage analytics data that's required to train a model.
The **Test configuration mode** option lets you build a model in a sandbox organization with little or infrequent usage analytics data so you can test the model.

When activated, this option reduces the amount of analytics data that's required to build the model.
It also reduces other frequency thresholds that discard queries or clicks that weren't performed frequently enough.

> **Note**
>
> The usage of certain frequency thresholds, or the selection of a specific value for these frequency thresholds depends on the configuration and implementation of the model.
> As the possible combinations of threshold configurations are adapted for each model, these frequency thresholds aren't listed in this section.

To activate the test configuration mode

. On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page, click the model for which you want to activate the test configuration mode, and then click **Edit** in the Action bar.

. On the subpage that opens, select the **Advanced** tab.

. In the left menu of the **Advanced** tab, select **Test configuration mode**.

. Select the **Activate test configuration mode** checkbox.

. Click **Save**.

### Advanced JSON model parameters

You can use the following JSON parameters when [configuring advanced settings](#advanced-configuration) for your [model](https://docs.coveo.com/en/1012/).

#### `automaticContextDiscovery` (boolean)

Sets whether the model evaluates custom usage analytics dimensions prefixed with `context_` to provide predictions or recommendations.

**Default**: `true`

When set to `false`, the model doesn't automatically consider user context found in data.
However, it will use user context fields defined in the [`userContextFields`](#usercontextfields-list-of-strings) parameter.

To set the parameter

[Access the model's JSON editor](#advanced-configuration), and then add the parameter configuration to the `extraConfig` object.

**Example**

You want to build a model that doesn't evaluate custom usage analytics dimensions prefixed with `context_`.
Therefore, you enter the following configuration in the `extraConfig` object:

```json
"extraConfig": {
    "automaticContextDiscovery": false
}
```

#### `commerceSupport` (object)

Whether the ART model should consider [cart](https://docs.coveo.com/en/n39h1594/) and [purchase](https://docs.coveo.com/en/l39m0327/) events to boost products on a commerce results page.

**Default**: `false`

When set to `true`, the ART model considers products that have been either purchased or added to a cart following a given query as items to be boosted for that particular query and automatically assign the required weight to each event.

To set the parameter

[Access the model's JSON editor](#advanced-configuration), and then add the parameter configuration to the `extraConfig` object.

**Example**

You want your ART model to consider cart and purchase events to boost products on a commerce results page.

Therefore, you enter the following configuration in the `extraConfig` object:

```json
"extraConfig": {
  "commerceSupport": {
    "enabled": true
  },
}
```

#### `filterFields` (list of strings)

Use this parameter to set the [Coveo Analytics](https://docs.coveo.com/en/182/) dimensions to be used as filters for potential suggestions.

The [model](https://docs.coveo.com/en/1012/) filters the suggestions so that only the interaction data from events that include the specified dimensions are considered.

**Default**: `["originLevel1", "originLevel2"]`.

> **Note**
>
> Given the default value of `["originLevel1", "originLevel2"]`, and the following implementation:
> 
> * Two `originLevel1` values: `partnerHub` and `techSupportHub`
> 
> * Four `originLevel2` values: `all`, `documentation`, `training`, and `community`
> 
> A total of eight possible filters will be created ( `partnerHub`/`all`, `techSupportHub`/`all`, `partnerHub`/`documentation`, etc.).
> This means that if a query originates from `partnerHub`/`all`, only interactions recorded in `partnerHub`/`all` will be used by the [model](https://docs.coveo.com/en/1012/) to make suggestions for that query.

> **Important**
>
> If you set a field other than the two default ones (`originLevel1` and `originLevel2`), you must also add the field at query time using the `filters` [mlParameter](https://docs.coveo.com/en/13#operation/searchUsingPost-mlParameters).

To set the parameter

[Access the model's JSON editor](#advanced-configuration), and then add the parameter configuration to the `extraConfig` object.

**Example**

You want your ML model to consider the possible value combination of the `originContext` and `originLevel2` dimensions when filtering results because some of the results are not available in some other combinations.

Therefore, you enter the following configuration in the `extraConfig` object:

```json
"extraConfig": {
    "filterFields": [
      "originContext",
      "originLevel2"
    ]
}
```

This would require sending the dimension values at query time in the `filters` [mlParameter](https://docs.coveo.com/en/13#operation/searchUsingPost-mlParameters/) as follows:

```json
"mlParameters": {
    "filters": {
          "originContext": "<MY-CONTEXT-VALUE>",
          "originLevel2": "<TAB-VALUE>"
    }
}
```

Moreover, you may want to build a model that doesn't use filters at all since all items are accessible everywhere.
You can do so by setting the `filterFields` parameter to empty in a model configuration.
This allows you to provide the same relevance across all search hubs using the model.

For example:

```json
"extraConfig": {
    "filterFields": []
}
```

#### `recommendProductGroup` (boolean)

Sets whether the model recommends [product groups](https://docs.coveo.com/en/l78i2152/) rather than individual items.

When set to `true`, the model uses [grouping fields](https://docs.coveo.com/en/l78i2152#grouping-field-configuration) to identify the content to recommend, ignoring the items' unique content ID (for example, `permanentid`).

To set the parameter

[Access the model's JSON editor](#advanced-configuration), and then add the parameter configuration to the `commerceSupport` object in `extraConfig`.

**Example**

You want your model to use groups of products rather than individual items when providing recommendations.

Therefore, you enter the following configuration in the [`commerceSupport`](#commercesupport-object) object:

```json
"extraConfig": {
    "commerceSupport": {
      "enabled": true,
      "recommendProductGroup": true
    }
  }
```

#### `userContextFields` (list of strings)

The usage analytics dimensions whose values should be used as the user context by the model to influence the ranking scores of items.

> **Important**
>
> When configuring the `userContextFields` advanced parameter, make sure that the related dimension values are sent at query time in the [`context`](https://docs.coveo.com/en/13#operation/searchUsingPost-context) parameter.

To set the parameter

[Access the model's JSON editor](#advanced-configuration), and then add the parameter configuration to the `extraConfig` object.

**Example**

You want to build an ML model that uses the `originLevel3` and `userGroups` usage analytics dimensions as the user context to influence the ranking scores of items.

Therefore, you enter the following configuration in the `extraConfig` object:

```json
"extraConfig": {
    "userContextFields": [
      "originLevel3",
      "userGroups"
    ]
}
```

### "Status" column

On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page of the [Administration Console](https://docs.coveo.com/en/183/), the **Status** column indicates the current state of your Coveo ML models.

The following table lists the possible model statuses and their definitions:

[%header,cols="1,6,^.^1"]
|===
.^|Status
.^|Definition
|Status icon

|Active
|The model is active and available.
a|![Active](leverage-machine-learning/model-active.png)

|Build in progress
|The model is currently building.
a|![Building](leverage-machine-learning/model-build.png)

|Inactive
|The model isn't ready to be queried, such as when a model was recently created or the organization is offline.  
Click **See more details** for additional information (see [Review model information](https://docs.coveo.com/en/1894/)).
a|![Inactive](leverage-machine-learning/model-limited.png)

|Limited
|Build issues exist that may affect model performance.  
Click **See more details** for additional information (see [Review model information](https://docs.coveo.com/en/1894/)).
a|![Limited](leverage-machine-learning/model-limited.png)

|Soon to be archived
|The model will soon be archived because it hasn't been queried for an extended period of time.  
Click **Delete** to remove the model.  
[Learn more about archived models](https://docs.coveo.com/en/mb3e0324/).
a|![Archive pending](leverage-machine-learning/model-limited.png)

|Error
|An error prevented the model from being built successfully.  
If it's a temporary system error, check back soon.
Otherwise, click **See more details** for additional information (see [Review model information](https://docs.coveo.com/en/1894/)).
a|![Error](leverage-machine-learning/model-error.png)

|Archived
|The model was archived because it hasn't been queried for an extended period of time.  
Click **Delete** to remove the model.  
[Learn more about archived models](https://docs.coveo.com/en/mb3e0324/).
a|![Archived](leverage-machine-learning/model-archived.png)
|===

### "Learning interval" section

In this section, you can modify the following:

* [[data-period]]**Data period**: The usage analytics data time interval on which the model will be based.
* **Building frequency**: The rate at which the model is retrained.

Set the Coveo ML model training **Building frequency** based on the **Data Period** value. Less frequent for a larger **Data Period** and more frequent for a smaller **Data Period** as recommended in the following table.

[cols="^3,^1,^1,^1"]
|===
.2+.^h|**Data period**
3+h|**Building frequency**

h|Daily
h|Weekly
h|Monthly

|1 month
|[check]
|[check]
|

|3 months (Recommended)
|
|[check]
|

|6 months
|
|
|[check]
|===

The more data the model has access to and learns from, the better the recommendations. As a general guide, a usage analytics dataset of 10,000 [queries](https://docs.coveo.com/en/231/) or more typically allows a Coveo ML model to provide very relevant recommendations. You can look at your [Coveo Analytics](https://docs.coveo.com/en/182/) data to evaluate the volume of queries on your search hub, and ensure that your Coveo ML models are configured with a training **Data period** that corresponds to at least 10,000 queries. When your [search hub](https://docs.coveo.com/en/1342/) serves a very high volume of queries, you can consider reducing the data period so that the model learns only more recent user behavior and be more responsive to trends.

A Coveo ML model regularly retrains on a more recent Coveo UA dataset, as determined by the **Building frequency** and **Data period** settings, to ensure that the model remains up-to-date with the most recent user behavior.

> **Note**
>
> If you're testing the model in a sandbox environment in which very little analytics data is available to train the model, you can activate the **Test configuration mode** [advanced option](#test-configuration-mode) to ensure the model provides recommendations.

## Required privileges

By default, members with the [required privileges](https://docs.coveo.com/en/1832#required-privileges) can view and edit elements of the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page.

The following table indicates the privileges required to use elements of the **Models** page and associated panels (see [Manage privileges](https://docs.coveo.com/en/3151/) and [Privilege reference](https://docs.coveo.com/en/1707/)).

[cols="3",options="header"]
|===
|Action
|Service - Domain
|Required access level

|View models
|Machine Learning - Models  
Organization - Organization  
Search - Query pipelines
|View

.2+|Edit models
|Organization - Organization  
Search - Query pipelines
|View

|Machine Learning - Models
|Edit
|===