Model advanced parameters (JSON editor)

This is for:

Developer System Administrator

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-ca | 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
}

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:

"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 (that is, ["originLevel1", "originLevel2"]), if there are two possible originLevel1 values (for example, partnerHub and techSupportHub) and four possible originLevel2 values (for example, 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 (that is, ["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 (for example, 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 commerceSupport object when configuring advanced parameters for your model:

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

userContextFields (list of strings)

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

Important

When configuring the userContextFields advanced parameter, make sure that the related dimension values are sent at query time in the context 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"
    ]
}

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 (that is, ["originLevel1", "originLevel2"]), if there are two possible originLevel1 values (for example, partnerHub and techSupportHub) and four possible originLevel2 values (for example, 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 (that is, ["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
}

queryReplacePatterns (list of tuples)

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

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

The second value of each tuple (that is, 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
}

recommendationStrategy (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 site’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": {
    "recommendationStrategy": "ipx"
}

urlReplacePatterns (list of tuples)

A set of patterns to find and reformat in URLs.

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

The second value of each tuple (that is, 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 (that is, ["originLevel1", "originLevel2"]), if there are two possible originLevel1 values (for example, partnerHub and techSupportHub) and four possible originLevel2 values (for example, 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 (that is, ["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": []
}

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 (for example, 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
}

Smart Snippets advanced model parameters

parsingMode (string)

By default, a Coveo ML Smart Snippet 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 information on how Smart Snippet models identify questions and answers from indexed items.

This behavior can be changed by setting the parsingMode parameter.

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 Snippet model to only use JSON-LD to identify questions and answers from within indexed items, ignoring the raw HTML.

Therefore, you set the parsingMode parameter in the extraConfig array as follows:

"extraConfig": {
  "parsingMode": "JsonldOnly"
}