Machine Learning Advanced Parameters

Machine Learning Advanced Parameters - Deprecated Methods

Leverage Machine Learning Coveo Relevance Cloud Developer System Administrator Product Documentation

In this article

Using the Machine Learning API
Using the Search API
Deprecated Parameters

This article shows deprecated ways of configuring advanced parameters in Coveo Machine Learning models. We recommend that you configure your advanced parameters using the Advanced tab of a model configuration instead.

When creating or updating a Coveo Machine Learning (Coveo ML) model, you can specify various advanced parameters to tailor the model to specific use cases. This article provides reference information on the available advanced model parameters.

The way you specify advanced model parameters varies slightly depending on whether your Coveo organization is managing its models globally (i.e., using the Machine Learning API), or per query pipeline (i.e., using the Search API).

Example

In the Administration Console, assuming you have the required privileges, if you can see the Add Model button in the upper-right corner of the Models (platform-eu | platform-au) page, then your organization is managing its models through the Machine Learning API. Otherwise, it’s doing so through the Search API.

For example, you want to create an Automatic Relevance Tuning (ART) model that requires a minimum of 500 usage analytics events to be built.

Aside from that, you want your model to use the standard recommended ART settings (i.e., refresh once a week using a data export covering the previous three months). Therefore, you enter the following JSON configuration when configuring your ART model:

If your organization is managing its models globally through the Machine Learning API, your JSON request body would look like this (see Creating a Model With JSON):

{
  "engineId": "topclicks",
  "modelDisplayName": "My ART Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.featureSelect.minEventsForModelBuilding=500"
  ]
}

If your organization is managing its models per pipeline through the Search API, its query pipeline language (QPL) definition would look like this (see Code Query Pipeline Rules):

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.featureSelect.minEventsForModelBuilding=500"]

In addition to the custom model parameters described in this article, you can also use the mlParameters query parameter to adjust the way your Coveo ML models are used at query time.

Examples

You can use the num mlParameter to change the number of suggestions provided by a Query Suggestions (QS) model or to modify the number of boosted results provided by an ART model.
You can use the wordSelection mlParameter and the wordsKept option to specify the number of ITD refined keywords to inject in a query used by an ART model before boosting results.

If your organization is managing its models globally (Machine Learning API), see Use the Machine Learning API.

If your organization is managing its models using query pipelines (Search API), see Use the Machine Learning API.

Using the Machine Learning API

If your organization manages its models globally (i.e., using the Machine Learning API), we recommend that you configure your advanced parameters using the Advanced Configuration section of a model configuration instead of the deprecated methods described in this section.

ART (topClicks) Advanced Model Parameters

`filterFields` (list of strings)

This parameter allows to select the Coveo Usage Analytics (Coveo UA) dimensions to be used as filters for potential suggestions. An item will be suggested by the model only if it has been clicked with the specified filter values.

Default value is the list ["originLevel1", "originLevel2"].

Note

With the default filterFields value (i.e., ["originLevel1", "originLevel2"]), if there are two possible originLevel1 values (e.g., partnerHub and techSupportHub) and four possible originLevel2 values (e.g., 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 partnerHub/all is received at query time, only the items clicked in partnerHub/all will be returned by the model.

Note that if you set another field than the two default ones (i.e., ["originLevel1", "originLevel2"]), you must also add the values at query time using the filters mlParameters.

Example

You want your ART 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 JSON configuration when configuring your ART model:

{
    "engineId": "topclicks",
    "modelDisplayName": "My ART Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.filterFields.0=originContext",
      "--conf",
      "coveo.drill.filterFields.1=originLevel2"
    ]
}

This would require sending the dimension values at query time in the filters mlParameters as follows:

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

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Builds distinct sub-models for every possible combination of the originContext and originLevel2 dimensions.

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

For example:

{
  "engineId": "topclicks",
  "modelDisplayName": "My ART Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.filterFields="
  ]
}

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Doesn’t build sub-models for different search hubs as the filterFields value is left empty.

`userContextFields` (list of strings)

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

When configuring the userContextFields advanced parameter, make sure that the related dimension values are sent at query time in the context query parameter.

Example

You want to build an ART 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 JSON configuration when configuring your ART model:

{
    "engineId": "topclicks",
    "modelDisplayName": "My ART Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.userContextFields.0=originLevel3",
      "--conf",
      "coveo.drill.userContextFields.1=userGroups"
    ]
}

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Uses the originLevel3 and userGroups usage analytics dimensions as the user context.

`automaticContextDiscovery` (boolean)

Whether the model should evaluate 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 parameter.

Example

You want to build an ART model that doesn’t evaluate custom usage analytics dimensions prefixed with context_. Therefore, you enter the following JSON configuration when configuring your ART model:

{
    "engineId": "topclicks",
    "modelDisplayName": "My ART Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.automaticContextDiscovery=false"
    ]
}

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Doesn’t automatically consider user context found in data.

`testConfiguration` (boolean)

Whether to activate the test configuration mode for this model. This parameter should be used in sandbox environments, when very little analytics are available to train a model.

Default: false

When set to true, the parameter reduces the amount of analytics data required to build the model. It also reduces other frequency thresholds that discard queries or clicks that were not performed frequently enough.

Note that 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 here.

Example

In a sandbox environment, you want to build an ART model that takes into account infrequent analytics data for its learning process (see ART prerequisites for model creation).

Therefore, you active the test configuration mode for the model as follows:

{
    "engineId": "topclicks",
    "modelDisplayName": "My ART Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.testConfiguration=true"
    ]
}

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Activates the test configuration mode.

`filterOutEmptyQueries` (boolean)

Whether the ART model ignores clicks following empty queries as valid usage analytics events to analyze.

Default value is true, meaning that ART models learn from the most clicked documents following non-empty queries only. When set to false, ART models also learn from the most clicked documents following empty queries.

Note

Regardless of the value (true or false), ART models still provide predictions (popular documents) for empty queries. The predictions are computed considering the filterFields parameter, which default behavior is to build different submodels for each search hub and tab. In other words, ART models will output popular documents clicked in the current search hub and tab.

Example

You want your ART model to consider clicks that followed empty queries. Therefore, you enter the following JSON configuration when configuring your ART model:

JSON (Machine Learning API)

{
    "engineId": "topclicks",
    "modelDisplayName": "My ART Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.filterOutEmptyQueries=false"
    ]
}

QPL (Search API)

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.filterOutEmptyQueries=false"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Considers click events that followed empty queries.

`whitelist` (list of strings)

The dimension key names (e.g., context keys) to include in the machine learning models by overriding the user context selection algorithm. The algorithm keeps all specified dimensions, meaning that the end-user experience is personalized according to these dimensions.

Default value is the list [].

Note

If the same context key is used in both blacklist and whitelist parameters, whitelist takes precedence.

Example

You want an ART model to override the user context selection algorithm with the c_context_brand and c_context_contact_primary_role dimension keys. Therefore, you enter the following JSON configuration when configuring your ART model:

{
    "engineId": "topclicks",
    "modelDisplayName": "My ART Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.featureSelect.whitelist.0=c_context_brand",
      "--conf",
      "coveo.drill.featureSelect.whitelist.1=c_context_contact_primary_role"
    ]
}

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Overrides the user context selection algorithm with the c_context_brand and c_context_contact_primary_role dimension keys.

`blacklist` (list of strings)

The dimension key names (e.g., context keys) to exclude from ML models by overriding the user context selection algorithm. This algorithm ignores all specified dimensions, meaning that the end-user experience isn’t personalized according to these dimensions.

Default value is an empty list ([]).

Note

If the same context key is used in both the blacklist and whitelist parameters, the whitelist takes precedence.

Example

You want an ART model to ignore the c_context_brand and c_context_contact_primary_role dimension keys from its learning process. Therefore, you enter the following JSON configuration when configuring your ART model:

{
    "engineId": "topclicks",
    "modelDisplayName": "My ART Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.featureSelect.blacklist.0=c_context_brand",
      "--conf",
      "coveo.drill.featureSelect.blacklist.1=c_context_contact_primary_role"
    ]
}

In this example, the ART model:

Gathers three months of data (excluding today’s date as an exportOffset is specified).
Is refreshed once a week.
Ignores the c_context_brand and c_context_contact_primary_role dimension keys from its learning process.

QS (querySuggest) Advanced Model Parameters

`filterFields` (list of strings)

Default value is the list ["originLevel1", "originLevel2"].

Note

Note that if you set another field than the two default ones (i.e., ["originLevel1", "originLevel2"]), you must also add the values at query time using the filters mlParameters.

Example

You want your QS 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 JSON configuration when configuring your QS model:

{
    "engineId": "querysuggest",
    "modelDisplayName": "My QS Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.filterFields.0=originContext",
      "--conf",
      "coveo.drill.filterFields.1=originLevel2"
    ]
}

This would require sending the dimension values at query time in the filters mlParameters as follows:

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

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Builds distinct sub-models for every possible combination of the originContext and originLevel2 dimensions.

For example:

{
  "engineId": "querysuggest",
  "modelDisplayName": "My QS Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.filterFields="
  ]
}

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Doesn’t build sub-models for different search hubs as the filterFields value is left empty.

`userContextFields` (list of strings)

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

When configuring the userContextFields advanced parameter, make sure that the related dimension values are sent at query time in the context query parameter.

Example

You want to build a QS 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 JSON configuration when configuring your QS model:

{
    "engineId": "querysuggest",
    "modelDisplayName": "My QS Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.userContextFields.0=originLevel3",
      "--conf",
      "coveo.drill.userContextFields.1=userGroups"
    ]
}

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Uses the originLevel3 and userGroups usage analytics dimensions as the user context.

`automaticContextDiscovery` (boolean)

Whether the model should evaluate 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 parameter.

Example

You want to build a QS model that doesn’t evaluate custom usage analytics dimensions prefixed with context_. Therefore, you enter the following JSON configuration when configuring your QS model:

{
    "engineId": "querysuggest",
    "modelDisplayName": "My QS Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.automaticContextDiscovery=false"
    ]
}

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Doesn’t automatically consider user context found in data.

`testConfiguration` (boolean)

Whether to activate the test configuration mode for this model. This parameter should be used in sandbox environments, when very little analytics are available to train a model.

Default: false

Example

In a sandbox environment, you want to build a QS model that takes into account infrequent analytics data for its learning process (see QS prerequisites for model creation).

Therefore, you active the test configuration mode for the model as follows:

{
    "engineId": "querysuggest",
    "modelDisplayName": "My QS Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.testConfiguration=true"
    ]
}

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Activates the test configuration mode.

`whiteList` (list of strings)

Default value is the list [].

Note

If the same context key is used in both blacklist and whitelist parameters, whitelist takes precedence.

Example

You want a QS model to override the user context selection algorithm with the c_context_brand and c_context_contact_primary_role dimension keys. Therefore, you enter the following JSON configuration when configuring your QS model:

{
    "engineId": "querysuggest",
    "modelDisplayName": "My QS Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.featureSelect.whitelist.0=c_context_brand",
      "--conf",
      "coveo.drill.featureSelect.whitelist.1=c_context_contact_primary_role"
    ]
}

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Overrides the user context selection algorithm with the c_context_brand and c_context_contact_primary_role dimension keys.

`blackList` (list of strings)

Default value is an empty list ([]).

Note

If the same context key is used in both the blacklist and whitelist parameters, the whitelist takes precedence.

Example

You want a QS model to ignore the c_context_brand and c_context_contact_primary_role dimension keys from its learning process. Therefore, you enter the following JSON configuration when configuring your QS model:

{
    "engineId": "querysuggest",
    "modelDisplayName": "My QS Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.featureSelect.blacklist.0=c_context_brand",
      "--conf",
      "coveo.drill.featureSelect.blacklist.1=c_context_contact_primary_role"
    ]
}

In this example, the QS model:

Gathers three months of data (excluding today’s date as an exportOffset is specified).
Is refreshed once a week.
Ignores the c_context_brand and c_context_contact_primary_role dimension keys from its learning process.

`queryReplacePatterns` (list of tuples)

A set of patterns to find and reformat in query suggestions.

The first value of each tuple (i.e., pattern) must be a regular expression to test against each original query suggestion.

The second value of each tuple (i.e., ordering) is the replacement pattern to apply when a query suggestion matching the pattern is found. Captured pattern groups can be referenced in the ordering pattern using $1, $2, etc.

Notes

The following characters aren’t supported in replacement patterns: (, ), [, ], { }.
Query suggestions are automatically lower-cased.

Example

You want your QS model to reformat the following query suggestions:

5551234567 to become 555-123-4567
abc123 to become 1a2b3c

Therefore, you enter the following JSON configuration when configuring your QS model:

{
  "engineId": "querysuggest",
  "modelDisplayName": "My Query Suggestions Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.queryReplacePatterns.0.pattern=(\d{3})(\d{3})(\d{4})",
    "--conf",
    "coveo.drill.queryReplacePatterns.0.ordering=$1-$2-$3",
    "--conf",
    "coveo.drill.queryReplacePatterns.1.pattern=(a)(b)(c)(1)(2)(3)",
    "--conf",
    "coveo.drill.queryReplacePatterns.1.ordering=$4$1$5$2$6$3"
  ]
}

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Reformats query suggestion patterns.

The Query suggestions format advanced parameter allows you to find specific patterns and reformat them in queries suggested by a Coveo ML QS model.

Example

You want your QS model to reformat 5551234567 to 555-123-4567.

Therefore, you configure the Query suggestions format advanced parameter as follows:

To configure the query suggestions format parameter

On the models page, click the QS model for which you want to configure the query suggestions format parameter, and then, in the Action bar, click Edit.
On the subpage that opens, select the Advanced tab.
At the upper-left corner, select Query suggestions format.
In the Enter the regular expression needed to find a pattern in query suggestions input, enter a regular expression that matches the pattern to find in query suggestions.
In the Replace by input, enter a replacement pattern to apply when a query suggestion matches the regex entered in the Regular expression matching the pattern to find input.
Click Save.

CR (eventRecommendation) Advanced Model Parameters

`userContextFields` (list of strings)

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

When configuring the userContextFields advanced parameter, make sure that the related dimension values are sent at query time in the context query parameter.

Example

You want to build an CR 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 JSON configuration when configuring your CR model:

{
    "engineId": "eventrecommendation",
    "modelDisplayName": "My CR Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.userContextFields.0=originLevel3",
      "--conf",
      "coveo.drill.userContextFields.1=userGroups"
    ]
}

In this example, the CR model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Uses the originLevel3 and userGroups usage analytics dimensions as the user context.

`automaticContextDiscovery` (boolean)

Whether the model should evaluate 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 parameter.

Example

You want to build an CR model that doesn’t evaluate custom usage analytics dimensions prefixed with context_. Therefore, you enter the following JSON configuration when configuring your CR model:

{
    "engineId": "eventrecommendation",
    "modelDisplayName": "My CR Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.automaticContextDiscovery=false"
    ]
}

In this example, the CR model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Doesn’t automatically consider user context found in data.

`testConfiguration` (boolean)

Whether to activate the test configuration mode for this model. This parameter should be used in sandbox environments, when very little analytics are available to train a model.

Default: false

When set to true, the parameter reduces the amount of analytics data required to build the model. It also reduces other frequency thresholds that discard browsing patterns that were not performed frequently enough.

Example

In a sandbox environment, you want to build a CR model that takes into account infrequent analytics data for its learning process (see CR prerequisites for model creation).

Therefore, you active the test configuration mode for the model as follows:

{
    "engineId": "eventrecommendation",
    "modelDisplayName": "My CR Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.testConfiguration=true"
    ]
}

In this example, the CR model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Activates the test configuration mode.

`urlReplacePatterns` (list of tuples)

A set of patterns to find and reformat in URLs.

The first value of each tuple (i.e., pattern) must be a regular expression to test against each URL.

The second value of each tuple (i.e., replace) is the replacement pattern to apply when a URL matching the pattern is found.

Example

You want your CR model to remove trailing labels in URLs.

Therefore, you enter the following JSON configuration when configuring your CR model:

{
  "engineId": "recommendations",
  "modelDisplayName": "My Content Recommendations Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.urlReplacePatterns.0.pattern=#.*",
    "--conf",
    "coveo.drill.urlReplacePatterns.0.ordering="""
  ]
}

In this example, the CR model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Removes trailing labels in URLs.

DNE (facetSense) Advanced Model Parameters

`filterFields` (list of strings)

Default value is the list ["originLevel1", "originLevel2"].

Note

Note that if you set another field than the two default ones (i.e., ["originLevel1", "originLevel2"]), you must also add the values at query time using the filters mlParameters.

Example

You want your DNE 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 JSON configuration when configuring your DNE model:

{
    "engineId": "facetsense",
    "modelDisplayName": "My DNE Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.filterFields.0=originContext",
      "--conf",
      "coveo.drill.filterFields.1=originLevel2"
    ]
}

This would require sending the dimension values at query time in the filters mlParameters query parameter as follows:

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

In this example, the DNE model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Builds distinct sub-models for every possible combination of the originContext and originLevel2 dimensions.

For example:

{
  "engineId": "facetsense",
  "modelDisplayName": "My DNE Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.filterFields="
  ]
}

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Doesn’t build sub-models for different search hubs as the filterFields value is left empty.

`testConfiguration` (boolean)

Whether to activate the test configuration mode for this model. This parameter should be used in sandbox environments, when very little analytics are available to train a model.

Default: false

Example

In a sandbox environment, you want to build a DNE model that takes into account infrequent analytics data for its learning process.

Therefore, you active the test configuration mode for the model as follows:

{
    "engineId": "facetsense",
    "modelDisplayName": "My DNE Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.testConfiguration=true"
    ]
}

In this example, the DNE model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Activates the test configuration mode.

PR (ecommerce) Advanced Model Parameters

`testConfiguration` (boolean)

Whether to activate the test configuration mode for this model. This parameter should be used in sandbox environments, when very little analytics are available to train a model.

Default: false

When set to true, the parameter reduces the amount of analytics data required to build the model. It also reduces other frequency thresholds that discard browsing and purchase patterns that were not performed frequently enough.

Example

In a sandbox environment, you want to build a PR model that takes into account infrequent analytics data for its learning process (see PR prerequisites for model creation).

Therefore, you active the test configuration mode for the model as follows:

{
    "engineId": "ecommerce",
    "modelDisplayName": "My PR Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.testConfiguration=true"
    ]
}

In this example, the PR model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Activates the test configuration mode.

Smart Snippets (mlquestionanswering) Advanced Model Parameters

`parsingMode` (string)

By default, a Coveo ML Smart Snippets model prioritizes content that contains JSON-LD, meaning that raw HTML is ignored when an item contains JSON-LD formatted content within its <head> section (see Optimize the Content for further information on how Smart Snippets models identify questions and answers from indexed items).

This behavior can be changed by setting the parsingMode parameter through the Update the information of a model operation of the Machine Learning API.

Default value: JsonldFallbackToHtml

Available options:

JsonldFallbackToHtml (default): When using this option, the model prioritizes JSON-LD formatted questions and answers. When no JSON-LD is found, the model uses the item’s raw HTML to identify questions and answers.
JsonldOnly: When using this option, the model only uses items that contain JSON-LD formatted questions and answers. When no JSON-LD is found within the item, this item is ignored by the model, meaning that the item’s raw HTML isn’t used by the model to identify questions and answers.
JsonldAndHtml: When using this option, the model uses both the JSON-LD and raw HTML of an item to identify questions and answers, meaning that no prioritization is done by the model.

Example

You want your Smart Snippets model to only use JSON-LD to identify questions and answers from within indexed items, ignoring the raw HTML.

Therefore, you update your model configuration by setting the parsingMode parameter in the commandLineParameters array as follows:

"commandLineParameters": [
  "--conf",
  "coveo.drill.parsingMode=JsonldOnly"
]

Using the Search API

ART (topClicks) Advanced Model Parameters

`filterFields` (list of strings)

Default value is the list ["originLevel1", "originLevel2"].

Note

Note that if you set another field than the two default ones (i.e., ["originLevel1", "originLevel2"]), you must also add the values at query time using the filters mlParameters.

Example

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.filterFields.0=originContext", "--conf", "coveo.drill.filterFields.1=originLevel2"]

This would require sending the dimension values at query time in the filters mlParameters as follows:

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

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Builds distinct sub-models for every possible combination of the originContext and originLevel2 dimensions.

For example:

querysuggest displayName: "My QS Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.filterFields="]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Doesn’t build sub-models for different search hubs as the filterFields value is left empty.

`userContextFields` (list of strings)

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

When configuring the userContextFields advanced parameter, make sure that the related dimension values are sent at query time in the context query parameter.

Example

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.userContextFields.0=originLevel3", "--conf", "coveo.drill.userContextFields.1=userGroups"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Uses the originLevel3 and userGroups usage analytics dimensions as the user context.

`automaticContextDiscovery` (boolean)

Whether the model should evaluate 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 parameter.

Example

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.automaticContextDiscovery=false"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Doesn’t automatically consider user context found in data.

`testConfiguration` (boolean)

Whether to activate the test configuration mode for this model. This parameter should be used in sandbox environments, when very little analytics are available to train a model.

Default: false

Example

In a sandbox environment, you want to build an ART model that takes into account infrequent analytics data for its learning process (see ART prerequisites for model creation).

Therefore, you active the test configuration mode for the model as follows:

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.testConfiguration=true"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Activates the test configuration mode.

`filterOutEmptyQueries` (boolean)

Whether the ART model ignores clicks following empty queries as valid usage analytics events to analyze.

Note

Example

You want your ART model to consider clicks that followed empty queries. Therefore, you enter the following JSON configuration when configuring your ART model:

JSON (Machine Learning API)

{
    "engineId": "topclicks",
    "modelDisplayName": "My ART Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.filterOutEmptyQueries=false"
    ]
}

QPL (Search API)

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.filterOutEmptyQueries=false"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Considers click events that followed empty queries.

`whitelist` (list of strings)

Default value is the list [].

Note

If the same context key is used in both blacklist and whitelist parameters, whitelist takes precedence.

Example

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.featureSelect.whitelist.0=c_context_brand", "--conf", "coveo.drill.featureSelect.whitelist.1=c_context_contact_primary_role"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Overrides the user context selection algorithm with the c_context_brand and c_context_contact_primary_role dimension keys.

`blacklist` (list of strings)

Default value is an empty list ([]).

Note

If the same context key is used in both the blacklist and whitelist parameters, the whitelist takes precedence.

Example

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.featureSelect.blacklist.0=c_context_brand", "--conf", "coveo.drill.featureSelect.blacklist.1=c_context_contact_primary_role"]

In this example, the ART model:

Gathers three months of data (excluding today’s date as an exportOffset is specified).
Is refreshed once a week.
Ignores the c_context_brand and c_context_contact_primary_role dimension keys from its learning process.

QS (querySuggest) Advanced Model Parameters

`filterFields` (list of strings)

Default value is the list ["originLevel1", "originLevel2"].

Note

Note that if you set another field than the two default ones (i.e., ["originLevel1", "originLevel2"]), you must also add the values at query time using the filters mlParameters.

Example

querySuggest displayName: "My QS Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.filterFields.0=originContext", "--conf", "coveo.drill.filterFields.1=originLevel2"]

This would require sending the dimension values at query time in the filters mlParameters as follows:

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

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Builds distinct sub-models for every possible combination of the originContext and originLevel2 dimensions.

For example:

querysuggest displayName: "My QS Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.filterFields="]

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Doesn’t build sub-models for different search hubs as the filterFields value is left empty.

`userContextFields` (list of strings)

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

When configuring the userContextFields advanced parameter, make sure that the related dimension values are sent at query time in the context query parameter.

Example

querysuggest displayName: "My QS Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.userContextFields.0=originLevel3", "--conf", "coveo.drill.userContextFields.1=userGroups"]

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Uses the originLevel3 and userGroups usage analytics dimensions as the user context.

`automaticContextDiscovery` (boolean)

Whether the model should evaluate 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 parameter.

Example

You want to build a QS model that doesn’t evaluate custom usage analytics dimensions prefixed with context_. Therefore, you enter the following JSON configuration when configuring your QS model:

querysuggest displayName: "My QS Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.automaticContextDiscovery=false"]

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Doesn’t automatically consider user context found in data.

`testConfiguration` (boolean)

Whether to activate the test configuration mode for this model. This parameter should be used in sandbox environments, when very little analytics are available to train a model.

Default: false

Example

In a sandbox environment, you want to build a QS model that takes into account infrequent analytics data for its learning process (see QS prerequisites for model creation).

Therefore, you active the test configuration mode for the model as follows:

querysuggest displayName: "My QS Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.testConfiguration=true"]

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Activates the test configuration mode.

`whiteList` (list of strings)

Default value is the list [].

Note

If the same context key is used in both blacklist and whitelist parameters, whitelist takes precedence.

Example

querysuggest displayName: "My QS Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.featureSelect.whitelist.0=c_context_brand", "--conf", "coveo.drill.featureSelect.whitelist.1=c_context_contact_primary_role"]

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Overrides the user context selection algorithm with the c_context_brand and c_context_contact_primary_role dimension keys.

`blackList` (list of strings)

Default value is an empty list ([]).

Note

If the same context key is used in both the blacklist and whitelist parameters, the whitelist takes precedence.

Example

querysuggest displayName: "My QS Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.featureSelect.blacklist.0=c_context_brand", "--conf", "coveo.drill.featureSelect.blacklist.1=c_context_contact_primary_role"]

In this example, the QS model:

Gathers three months of data (excluding today’s date as an exportOffset is specified).
Is refreshed once a week.
Ignores the c_context_brand and c_context_contact_primary_role dimension keys from its learning process.

`queryReplacePatterns` (list of tuples)

A set of patterns to find and reformat in query suggestions.

The first value of each tuple (i.e., pattern) must be a regular expression to test against each original query suggestion.

Notes

The following characters aren’t supported in replacement patterns: (, ), [, ], { }.
Query suggestions are automatically lower-cased.

Example

You want your QS model to reformat the following query suggestions:

5551234567 to become 555-123-4567
abc123 to become 1a2b3c

Therefore, you enter the following JSON configuration when configuring your QS model:

querySuggest displayName: "My Query Suggestions Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.queryReplacePatterns.0.pattern=(\d{3})(\d{3})(\d{4})", "--conf", "coveo.drill.queryReplacePatterns.0.ordering=$1-$2-$3", "--conf", "coveo.drill.queryReplacePatterns.1.pattern=((a)(b)(c)(1)(2)(3))", "--conf", "coveo.drill.queryReplacePatterns.1.ordering=$4$1$5$2$6$3"]

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Reformats query suggestion patterns.

The Query suggestions format advanced parameter allows you to find specific patterns and reformat them in queries suggested by a Coveo ML QS model.

Example

You want your QS model to reformat 5551234567 to 555-123-4567.

Therefore, you configure the Query suggestions format advanced parameter as follows:

To configure the query suggestions format parameter

On the models page, click the QS model for which you want to configure the query suggestions format parameter, and then, in the Action bar, click Edit.
On the subpage that opens, select the Advanced tab.
At the upper-left corner, select Query suggestions format.
In the Enter the regular expression needed to find a pattern in query suggestions input, enter a regular expression that matches the pattern to find in query suggestions.
In the Replace by input, enter a replacement pattern to apply when a query suggestion matches the regex entered in the Regular expression matching the pattern to find input.
Click Save.

CR (eventRecommendation) Advanced Model Parameters

`userContextFields` (list of strings)

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

When configuring the userContextFields advanced parameter, make sure that the related dimension values are sent at query time in the context query parameter.

Example

eventrecommendation displayName: "My CR Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.userContextFields.0=originLevel3", "--conf", "coveo.drill.userContextFields.1=userGroups"]

In this example, the CR model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Uses the originLevel3 and userGroups usage analytics dimensions as the user context.

`automaticContextDiscovery` (boolean)

Whether the model should evaluate 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 parameter.

Example

You want to build an CR model that doesn’t evaluate custom usage analytics dimensions prefixed with context_. Therefore, you enter the following JSON configuration when configuring your CR model:

eventrecommendation displayName: "My CR Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.automaticContextDiscovery=false"]

In this example, the CR model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Doesn’t automatically consider user context found in data.

`testConfiguration` (boolean)

Whether to activate the test configuration mode for this model. This parameter should be used in sandbox environments, when very little analytics are available to train a model.

Default: false

Example

In a sandbox environment, you want to build a CR model that takes into account infrequent analytics data for its learning process (see CR prerequisites for model creation).

Therefore, you active the test configuration mode for the model as follows:

eventrecommendation displayName: "My CR Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.testConfiguration=true"]

In this example, the CR model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Activates the test configuration mode.

`urlReplacePatterns` (list of tuples)

A set of patterns to find and reformat in URLs.

The first value of each tuple (i.e., pattern) must be a regular expression to test against each URL.

The second value of each tuple (i.e., replace) is the replacement pattern to apply when a URL matching the pattern is found.

Example

You want your CR model to remove trailing labels in URLs.

Therefore, you enter the following JSON configuration when configuring your CR model:

recommendations displayName: "My Content Recommendations Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.urlReplacePatterns.0.pattern=(#.*)", "--conf", "coveo.drill.urlReplacePatterns.0.pattern=#.*", "--conf", "coveo.drill.urlReplacePatterns.0.ordering="""]

In this example, the CR model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Removes trailing labels in URLs.

DNE (facetSense) Advanced Model Parameters

`filterFields` (list of strings)

Default value is the list ["originLevel1", "originLevel2"].

Note

Note that if you set another field than the two default ones (i.e., ["originLevel1", "originLevel2"]), you must also add the values at query time using the filters mlParameters.

Example

facetSense displayName: "My DNE Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.filterFields.0=originContext", "--conf", "coveo.drill.filterFields.1=originLevel2"]

This would require sending the dimension values at query time in the filters mlParameters as follows:

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

In this example, the DNE model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Builds distinct sub-models for every possible combination of the originContext and originLevel2 dimensions.

For example:

facetsense displayName: "My DNE Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.filterFields="]

In this example, the DNE model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Doesn’t build sub-models for different search hubs as the filterFields value is left empty.

`testConfiguration` (boolean)

Whether to activate the test configuration mode for this model. This parameter should be used in sandbox environments, when very little analytics are available to train a model.

Default: false

Example

In a sandbox environment, you want to build a DNE model that takes into account infrequent analytics data for its learning process.

Therefore, you active the test configuration mode for the model as follows:

facetsense displayName: "My DNE Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.testConfiguration=true"]

In this example, the DNE model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Activates the test configuration mode.

PR (ecommerce) Advanced Model Parameters

`testConfiguration` (boolean)

Whether to activate the test configuration mode for this model. This parameter should be used in sandbox environments, when very little analytics are available to train a model.

Default: false

Example

In a sandbox environment, you want to build a PR model that takes into account infrequent analytics data for its learning process (see PR prerequisites for model creation).

Therefore, you active the test configuration mode for the model as follows:

ecommerce displayName: "My PR Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.testConfiguration=true"]

In this example, the PR model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Activates the test configuration mode.

Deprecated Parameters

This section lists the deprecated Coveo ML advanced parameters. These parameters can still be used in a model configuration, but are no longer recommended.

Generic Deprecated Parameters

`anonymousUserIds` (list of strings) - Deprecated

The usernames that should be interpreted as anonymous by the model.

Default value is an empty list ([]), meaning only the usernames that are automatically detected as anonymous will be considered as such by the model.

Example

You want an ART model to consider both anonymous@anonymous and johndoe@anonymous.com as anonymous users. Therefore, you enter the following JSON configuration when configuring your ART model:

JSON (Machine Learning API)

{
  "engineId": "topclicks",
  "modelDisplayName": "My ART Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.dataCleaning.anonymousUserIds.0=anonymous@anonymous",
    "--conf",
    "coveo.drill.dataCleaning.anonymousUserIds.1=johndoe@anonymous.com"
  ]
}

QPL (Search API):

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.dataCleaning.anonymousUserIds.0=anonymous@anonymous", "--conf", "coveo.drill.dataCleaning.anonymousUserIds.1=johndoe@anonymous.com"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Considers both anonymous@anonymous and johndoe@anonymous.com as anonymous users.

`minEventsForModelBuilding` (unsigned integer) - Deprecated

The minimum number of events that the usage analytics data of the Coveo organization must contain for a model to be built. If fewer usage analytics events have been logged, an empty model will be returned.

Default value is 100. Specified value must be in the range [0, 10000].

Example

You want to build an ART model that requires a minimum of 1250 usage analytics events. Therefore, you enter the following JSON configuration when configuring your ART model:

JSON (Machine Learning API)

{
  "engineId": "topclicks",
  "modelDisplayName": "My ART Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.minEventsForModelBuilding=1250"
  ]
}

QPL (Search API):

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.minEventsForModelBuilding=1250"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Requires a minimum of 1250 usage analytics events before being built.

ART (topClicks) Deprecated Parameters

`filterOutEmptyQueries` (boolean) - Deprecated

Whether the ART model ignores clicks following empty queries as valid usage analytics events to analyze.

Note

Example

You want your ART model to consider clicks that followed empty queries. Therefore, you enter the following JSON configuration when configuring your ART model:

JSON (Machine Learning API)

{
    "engineId": "topclicks",
    "modelDisplayName": "My ART Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.filterOutEmptyQueries=false"
    ]
}

QPL (Search API)

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.filterOutEmptyQueries=false"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Considers click events that followed empty queries.

`maxEventsPerVisit` (unsigned integer) - Deprecated

The maximum number of usage analytics events (Click, Custom, Search, and View) a visit can contain to be taken into account when building/updating the ART model. All visits containing more usage analytics events than this threshold value will be filtered out.

Default value is 30. Specified value must be in the range [10, 100].

Example

You want your ART model to only take into account visits that contained a maximum of 55 usage analytics events. Therefore, you enter the following JSON configuration when configuring your ART model:

JSON (Machine Learning API)

{
  "engineId": "topclicks",
  "modelDisplayName": "My ART Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.maxEventsPerVisit=55"
  ]
}

QPL (Search API):

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.maxEventsPerVisit=55"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Takes only into account visits that contained a maximum of 55 usage analytics events.

`maxClicksOfUserPerDocQuery` (integer) - Deprecated

The maximum number of usage analytics Click events per user per item to take into account when building/updating the ART or QS model. Subsequent Click events logged by the same user for the same item will be filtered out.

Default value is 2. Allowed values: -1, or any value in the range [1, 100].

Note

Set maxClicksOfUserPerDocQuery to -1 to deactivate the feature entirely (i.e., take all usage analytics Click events into account).

Example

You want to build an ART model that considers the first 80 click events per user for a specific item. Therefore, you enter the following JSON configuration when configuring your ART model:

JSON (Machine Learning API)

{
  "engineId": "topclicks",
  "modelDisplayName": "My ART Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.minClicksPerContext=80"
  ]
}

QPL (Search API):

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.minClicksPerContext=80"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Considers the first 80 click events made per user for a specific item.

`wordWeightMinQueryCount` (unsigned integer) - Deprecated

The number of times a specific basic query expression (q) needs to be executed before it can be considered for Intelligent Term Detection (ITD).

Default value is 5. Specified value must be in the range [1, 100].

Example

You want your ART model to consider only basic query expressions (q) that have been executed 25 times as Intelligent Term Detection (ITD) candidates. Therefore, you enter the following JSON configuration when configuring your ART model:

JSON (Machine Learning API)

{
  "engineId": "topclicks",
  "modelDisplayName": "My ART Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.wordWeightMinQueryCount=25"
  ]
}

QPL (Search API):

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.wordWeightMinQueryCount=25"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Considers only basic query expressions (q) that have been executed 25 times as ITD candidates.

`minClicksPerContext` (unsigned integer) - Deprecated

The number of times a query result item matching a specific user context needs to be opened (i.e., clicked or previewed) before the ART model recognizes and stores a causal relationship between the context and opening the item (see userContextFields and userContextPrefix).

Default value is 25. Specified value must be in the range [1, 200].

Example

You want your ART model to recognize a relationship between a result item and a specific user context when a result item matching the user context has been opened at least 120 times. Therefore, you enter the following JSON configuration when configuring your ART model:

JSON (Machine Learning API)

{
  "engineId": "topclicks",
  "modelDisplayName": "My ART Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.minClicksPerContext=120"
  ]
}

QPL (Search API):

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.minClicksPerContext=120"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Recognizes a relationship between a result item and a specific user context when a result item matching the user context has been opened at least 120 times.

`minClicksPerQuery` (integer) - Deprecated

The number of times a query result item matching a specific basic query expression (q) needs to be opened (i.e., clicked or previewed) before the ART model recognizes and stores a causal relationship between that expression and the item.

Default value is 3.

Note

Set minClicksPerQuery to a value equal to or lower than 1 to have the model recognize/store a relationship between an item and expression as soon as the item has been opened at least once.

Example

You want an ART model to start recognizing the relationship between a query and a result item when the item has been opened ten times following a specific basic query expression. Therefore, you enter the following JSON configuration when configuring your ART model:

JSON (Machine Learning API):

{
    "engineId": "topclicks",
    "modelDisplayName": "My ART Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.minClicksPerQuery=10"
    ]
}

QPL (Search API):

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.minClicksPerQuery=10"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Recognizes the relationship between a query and a result item when the item has been opened ten times following a specific basic query expression (q).

`userContextPrefix` (string) - Deprecated

The prefix a usage analytics event customData key must have to be recognized by the ART or QS model as an additional userContextFields dimension (see userContextFields).

Default value is c_context_.

Note

The value for this parameter must mandatorily start with c_. However:

While customData keys intended to be leveraged as user context must be properly prefixed when included in a request to log a Click, Custom, Search, or View event through the Usage Analytics Write API, the heading c_ must not be included in the prefix (e.g., use context_role, not c_context_role).
Search API query context keys must not be prefixed at all because they’re already in the context object (e.g., use role, not context_role or c_context_role).

Example

You want the c_my_context_ usage analytics event prefix to be recognized by your ART model as an additional userContextFields dimension. Therefore, you enter the following JSON configuration when configuring your ART model:

JSON (Machine Learning API)

{
  "engineId": "topclicks",
  "modelDisplayName": "My ART Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.userContextPrefix=c_my_context_"
  ]
}

QPL (Search API):

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.userContextPrefix=c_my_context_"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Uses c_my_context_ usage analytics event prefix as an additional userContextFields dimension.

QS (querySuggest) Deprecated Parameters

`minClicksPerQuery` (integer) - Deprecated

The number of times a query result item matching a specific basic query expression (q) needs to be opened (i.e., clicked or previewed) before the QS model recognizes and stores a causal relationship between that expression and the item.

Default value is 3.

Note

Set minClicksPerQuery to a value equal to or lower than 1 to have the model recognize/store a relationship between an item and expression as soon as the item has been opened at least once.

Example

You want a QS model to start recognizing the relationship between a query and a result item when the item has been opened ten times following a specific basic query expression. Therefore, you enter the following JSON configuration when configuring your QS model:

JSON (Machine Learning API):

{
    "engineId": "querysuggest",
    "modelDisplayName": "My QS Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commandLineParameters": [
      "--conf",
      "coveo.drill.minClicksPerQuery=10"
    ]
}

QPL (Search API):

querysuggest displayName: "My QS Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.minClicksPerQuery=10"]

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Recognizes the relationship between a query and a result item when the item has been opened ten times following a specific basic query expression (q).

`minContextCount` (integer) - Deprecated

The number of times any given user context key-value must be sent along a basic query expression (q) before the QS model recognizes and stores a relationship between that user context and the basic query expression.

Default value is 25. Specified value must be greater than or equal to 1.

Example

You want your QS model to recognize a relationship between a user context key-value and a basic query expression (q) when that user context has been sent along with the q at least 75 times. Therefore, you enter the following JSON configuration when configuring your QS model:

JSON (Machine Learning API)

{
  "engineId": "querysuggest",
  "modelDisplayName": "My Query Suggestions Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.minContextCount=75"
  ]
}

QPL (Search API):

  querySuggest displayName: "My Query Suggestions Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.minContextCount=75"]

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Recognizes a relationship between a user context key-value and a basic query expression (q) when that user context has been sent along with the q at least 75 times.

`maxDefaultQueryScore` (integer) - Deprecated

The maximum score that the default queries will be normalized to (e.g., [0, maxDefaultScore]). Default queries are used to kick-start query suggest models and will always be considered when making suggestions (even without usage analytics data).

Default value is 5. Specified value must be in the range [0, 50].

Example

You want your QS model to set the score of the default queries to a maximum of 15. Therefore, you enter the following JSON configuration when configuring your QS model:

JSON (Machine Learning API)

{
  "engineId": "querysuggest",
  "modelDisplayName": "My Query Suggestions Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.maxDefaultQueryScore=15"
  ]
}

QPL (Search API):

querySuggest displayName: "My Query Suggestions Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.maxDefaultQueryScore=15"]

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Sets the score of the default queries to a maximum of 15.

`maxClicksOfUserPerDocQuery` (integer) - Deprecated

Default value is 2. Allowed values: -1, or any value in the range [1, 100].

Note

Set maxClicksOfUserPerDocQuery to -1 to deactivate the feature entirely (i.e., take all usage analytics Click events into account).

Example

You want to build an ART model that considers the first 80 click events per user for a specific item. Therefore, you enter the following JSON configuration when configuring your ART model:

JSON (Machine Learning API)

{
  "engineId": "topclicks",
  "modelDisplayName": "My ART Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.minClicksPerContext=80"
  ]
}

QPL (Search API):

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.minClicksPerContext=80"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Considers the first 80 click events made per user for a specific item.

`maxDefaultLength` (integer) - Deprecated

The maximum number of characters a basic query expression (q) may contain to be considered a potential candidate by the QS model.

Default value is 75. Specified value must be in the range [1, 150].

Example

You want your QS model to consider basic query expressions (q) that contain up to 100 characters as potential query candidates. Therefore, you enter the following JSON configuration when configuring your QS model:

JSON (Machine Learning API)

{
  "engineId": "querysuggest",
  "modelDisplayName": "My Query Suggestions Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.maxDefaultLength=100"
  ]
}

QPL (Search API):

querySuggest displayName: "My Query Suggestions Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.maxDefaultLength=100"]

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Considers only basic query expressions (q) that contain a maximum 100 characters as potential query candidates.

`maxNumContexts` (integer) - Deprecated

The maximum number of context key-values that can be stored in the QS model.

Default value is 2000. Specified value must be in the range [5, 2000].

Example

You want your QS model to store a maximum of 950 of context key-values. Therefore, you enter the following JSON configuration when configuring your QS model:

JSON (Machine Learning API)

{
  "engineId": "querysuggest",
  "modelDisplayName": "My Query Suggestions Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.maxNumContexts=950"
  ]
}

QPL (Search API):

querySuggest displayName: "My Query Suggestions Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.maxNumContexts=950"]

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Stores a maximum of 950 of context key-values.

`useClustering` (boolean) - Deprecated

Whether to use clustering on the QS model. This will cluster users into groups and boost the query suggestion candidates which are popular within the same group of users. Users are grouped based on the queries they made and the items they clicked (i.e., users performing similar queries or viewing similar items are grouped together).

Default value is true.

Example

You don’t want your QS model to cluster users into groups. Therefore, you enter the following JSON configuration when configuring your QS model:

JSON (Machine Learning API)

{
  "engineId": "querysuggest",
  "modelDisplayName": "My Query Suggestions Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.useClustering=false"
  ]
}

QPL (Search API):

querySuggest displayName: "My Query Suggestions Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.useClustering=false"]

In this example, the QS model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Cluster similar users into groups.

`userContextPrefix` (string) - Deprecated

The prefix a usage analytics event customData key must have to be recognized by the ART or QS model as an additional userContextFields dimension (see userContextFields).

Default value is c_context_.

Note

The value for this parameter must mandatorily start with c_. However:

While customData keys intended to be leveraged as user context must be properly prefixed when included in a request to log a Click, Custom, Search, or View event through the Usage Analytics Write API, the heading c_ must not be included in the prefix (e.g., use context_role, not c_context_role).
Search API query context keys must not be prefixed at all because they’re already in the context object (e.g., use role, not context_role or c_context_role).

Example

JSON (Machine Learning API)

{
  "engineId": "topclicks",
  "modelDisplayName": "My ART Model",
  "exportPeriod": "P3M",
  "intervalTime": 1,
  "intervalUnit": "WEEK",
  "commandLineParameters": [
    "--conf",
    "coveo.drill.userContextPrefix=c_my_context_"
  ]
}

QPL (Search API):

topClicks displayName: "My ART Model", exportPeriod: "P3M", refreshRate: "P1W", customModelParameters: ["--conf", "coveo.drill.userContextPrefix=c_my_context_"]

In this example, the ART model:

Gathers three months of data (including today’s date as no exportOffset is specified).
Is refreshed once a week.
Uses c_my_context_ usage analytics event prefix as an additional userContextFields dimension.

Was this article useful?

Very useful

Not really

What's next for me?

Machine Learning Advanced Parameters - Deprecated Methods

Machine Learning Advanced Parameters - Deprecated Methods

Using the Machine Learning API

ART (topClicks) Advanced Model Parameters

filterFields (list of strings)

userContextFields (list of strings)

automaticContextDiscovery (boolean)

testConfiguration (boolean)

filterOutEmptyQueries (boolean)

whitelist (list of strings)

blacklist (list of strings)

QS (querySuggest) Advanced Model Parameters

filterFields (list of strings)

userContextFields (list of strings)

automaticContextDiscovery (boolean)

testConfiguration (boolean)

whiteList (list of strings)

blackList (list of strings)

queryReplacePatterns (list of tuples)

CR (eventRecommendation) Advanced Model Parameters

userContextFields (list of strings)

automaticContextDiscovery (boolean)

testConfiguration (boolean)

urlReplacePatterns (list of tuples)

DNE (facetSense) Advanced Model Parameters

filterFields (list of strings)

testConfiguration (boolean)

PR (ecommerce) Advanced Model Parameters

testConfiguration (boolean)

Smart Snippets (mlquestionanswering) Advanced Model Parameters

parsingMode (string)

Using the Search API

ART (topClicks) Advanced Model Parameters

filterFields (list of strings)

userContextFields (list of strings)

automaticContextDiscovery (boolean)

testConfiguration (boolean)

filterOutEmptyQueries (boolean)

whitelist (list of strings)

blacklist (list of strings)

QS (querySuggest) Advanced Model Parameters

filterFields (list of strings)

userContextFields (list of strings)

automaticContextDiscovery (boolean)

testConfiguration (boolean)

whiteList (list of strings)

blackList (list of strings)

queryReplacePatterns (list of tuples)

CR (eventRecommendation) Advanced Model Parameters

userContextFields (list of strings)

automaticContextDiscovery (boolean)

testConfiguration (boolean)

urlReplacePatterns (list of tuples)

DNE (facetSense) Advanced Model Parameters

filterFields (list of strings)

testConfiguration (boolean)

PR (ecommerce) Advanced Model Parameters

testConfiguration (boolean)

Deprecated Parameters

Generic Deprecated Parameters

anonymousUserIds (list of strings) - Deprecated

minEventsForModelBuilding (unsigned integer) - Deprecated

ART (topClicks) Deprecated Parameters

filterOutEmptyQueries (boolean) - Deprecated

maxEventsPerVisit (unsigned integer) - Deprecated

maxClicksOfUserPerDocQuery (integer) - Deprecated

wordWeightMinQueryCount (unsigned integer) - Deprecated

minClicksPerContext (unsigned integer) - Deprecated

minClicksPerQuery (integer) - Deprecated

userContextPrefix (string) - Deprecated

QS (querySuggest) Deprecated Parameters

minClicksPerQuery (integer) - Deprecated

minContextCount (integer) - Deprecated

maxDefaultQueryScore (integer) - Deprecated

maxClicksOfUserPerDocQuery (integer) - Deprecated

maxDefaultLength (integer) - Deprecated

maxNumContexts (integer) - Deprecated

useClustering (boolean) - Deprecated

userContextPrefix (string) - Deprecated

`filterFields` (list of strings)

`userContextFields` (list of strings)

`automaticContextDiscovery` (boolean)

`testConfiguration` (boolean)

`filterOutEmptyQueries` (boolean)

`whitelist` (list of strings)

`blacklist` (list of strings)

`filterFields` (list of strings)

`userContextFields` (list of strings)

`automaticContextDiscovery` (boolean)

`testConfiguration` (boolean)

`whiteList` (list of strings)

`blackList` (list of strings)

`queryReplacePatterns` (list of tuples)

`userContextFields` (list of strings)

`automaticContextDiscovery` (boolean)

`testConfiguration` (boolean)

`urlReplacePatterns` (list of tuples)

`filterFields` (list of strings)

`testConfiguration` (boolean)

`testConfiguration` (boolean)

`parsingMode` (string)

`filterFields` (list of strings)

`userContextFields` (list of strings)

`automaticContextDiscovery` (boolean)

`testConfiguration` (boolean)

`filterOutEmptyQueries` (boolean)

`whitelist` (list of strings)

`blacklist` (list of strings)

`filterFields` (list of strings)

`userContextFields` (list of strings)

`automaticContextDiscovery` (boolean)

`testConfiguration` (boolean)

`whiteList` (list of strings)

`blackList` (list of strings)

`queryReplacePatterns` (list of tuples)

`userContextFields` (list of strings)

`automaticContextDiscovery` (boolean)

`testConfiguration` (boolean)

`urlReplacePatterns` (list of tuples)

`filterFields` (list of strings)

`testConfiguration` (boolean)

`testConfiguration` (boolean)

`anonymousUserIds` (list of strings) - Deprecated

`minEventsForModelBuilding` (unsigned integer) - Deprecated

`filterOutEmptyQueries` (boolean) - Deprecated

`maxEventsPerVisit` (unsigned integer) - Deprecated

`maxClicksOfUserPerDocQuery` (integer) - Deprecated

`wordWeightMinQueryCount` (unsigned integer) - Deprecated

`minClicksPerContext` (unsigned integer) - Deprecated

`minClicksPerQuery` (integer) - Deprecated

`userContextPrefix` (string) - Deprecated

`minClicksPerQuery` (integer) - Deprecated

`minContextCount` (integer) - Deprecated

`maxDefaultQueryScore` (integer) - Deprecated

`maxClicksOfUserPerDocQuery` (integer) - Deprecated

`maxDefaultLength` (integer) - Deprecated

`maxNumContexts` (integer) - Deprecated

`useClustering` (boolean) - Deprecated

`userContextPrefix` (string) - Deprecated