Machine Learning Advanced Parameters (JSON Editor)

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.

Notes

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.

Specify Advanced Parameters

  1. On the Models (platform-eu | platform-au) page, click the model for which you want to add advanced parameters.

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

  3. In the JSON editor, enter the desired configuration in the extraConfig object. Available parameters differ depending on the type of model for which you want to specify an advanced configuration:

Reference

Automatic Relevance Tuning (ART) Advanced Model Parameters

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 ML model that doesn’t evaluate custom usage analytics dimensions prefixed with context_. Therefore, you enter the following configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
    "automaticContextDiscovery": false
}

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 configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
  "featureSelect": {
    "blacklist": [
          "c_context_brand",
          "c_context_contact_primary_role"
      ]
  }
}

commerceSupport (object)

Whether the ART model should consider cart and purchase usage analytics 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.

Example

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

Therefore, you enter the following configuration in the extraConfig object when configuring your ART model:

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

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 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 when configuring advanced parameters for your model:

"extraConfig": {
    "filterFields": [
      "originContext",
      "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>"
    }
}

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:

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

recommendProductGroup (boolean)

Whether the model should recommend product groups rather than individual items.

When set to true, the model uses grouping fields to identify the content to recommend, ignoring the items' unique content ID (e.g., permanentId).

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 extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
    "recommendProductGroup": true
}

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 a ML model that takes into account infrequent analytics data for its learning process.

Therefore, you enter the following configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
    "testConfiguration": 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 query parameter.

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 when configuring advanced parameters for your model:

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

whitelist (list of strings)

The dimension key names (e.g., context keys) to include in the machine learning model 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 ML 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 configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
  "featureSelect": {
    "whitelist": [
          "c_context_brand",
          "c_context_contact_primary_role"
      ]
  }
}

Query Suggestions (QS) 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 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 when configuring advanced parameters for your model:

"extraConfig": {
    "filterFields": [
      "originContext",
      "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>"
    }
}

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:

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

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 query parameter.

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 when configuring advanced parameters for your model:

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

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 ML model that doesn’t evaluate custom usage analytics dimensions prefixed with context_.

Therefore, you enter the following configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
    "automaticContextDiscovery": false
}

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 a ML model that takes into account infrequent analytics data for its learning process.

Therefore, you enter the following configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
    "testConfiguration": true
}

whiteList (list of strings)

The dimension key names (e.g., context keys) to include in the machine learning model 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 ML 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 configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
  "featureSelect": {
    "whitelist": [
          "c_context_brand",
          "c_context_contact_primary_role"
      ]
  }
}

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 configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
  "featureSelect": {
    "blacklist": [
          "c_context_brand",
          "c_context_contact_primary_role"
      ]
  }
}

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 configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
  "queryReplacePatterns": [
    {
      "pattern": "(\\d{3})(\\d{3})(\\d{4})",
      "ordering": "$1-$2-$3"
    },
    {
      "pattern": "(a)(b)(c)(1)(2)(3)",
      "ordering": "$4$1$5$2$6$3"
    }
  ]
}

Content Recommendations (CR) Advanced Model Parameters

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 query parameter.

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 when configuring advanced parameters for your model:

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

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 ML model that doesn’t evaluate custom usage analytics dimensions prefixed with context_.

Therefore, you enter the following configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
    "automaticContextDiscovery": false
}

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.

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 a ML model that takes into account infrequent analytics data for its learning process.

Therefore, you enter the following configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
    "testConfiguration": true
}

recommendationUseCase (string)

Sets the usage analytics configuration needed for a CR model that’s attached to a Coveo In-Product Experience (IPX) interface.

You can configure the model to recommend items in an IPX interface based on the user’s current location on the website by using the ipx recommendation use case.

Depending on the page a user is currently viewing, the CR model recommends items in the IPX interface that pertains to the current website’s URL. This gives a user access to the most relevant items based on their location on the website.

Example

You want your ML model to recommend items in an IPX interface that are relevant to the page the user is currently viewing.

Therefore, you enter the following configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
    "recommendationUseCase": "ipx"
}

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 configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
  "urlReplacePatterns": [
    {
      "pattern": "#.*",
      "replace": ""
    }
  ]
}

Dynamic Navigation Experience (DNE) 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 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 when configuring advanced parameters for your model:

"extraConfig": {
    "filterFields": [
      "originContext",
      "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>"
    }
}

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:

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

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 a ML model that takes into account infrequent analytics data for its learning process.

Therefore, you enter the following configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
    "testConfiguration": true
}

Product Recommendations (PR) Advanced Model Parameters

recommendProductGroup (boolean)

Whether the model should recommend product groups rather than individual items.

When set to true, the model uses grouping fields to identify the content to recommend, ignoring the items' unique content ID (e.g., permanentId).

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 extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
    "recommendProductGroup": true
}

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.

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 a ML model that takes into account infrequent analytics data for its learning process.

Therefore, you enter the following configuration in the extraConfig object when configuring advanced parameters for your model:

"extraConfig": {
    "testConfiguration": true
}