Machine Learning Advanced Parameters - Deprecated Methods
Machine Learning Advanced Parameters - Deprecated Methods
|
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).
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.
-
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 thewordsKept
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 Note that if you set another field than the two default ones ( |
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
andoriginLevel2
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 |
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
anduserGroups
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.
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.
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 ( |
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 |
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
andc_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 |
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
andc_context_contact_primary_role
dimension keys from its learning process.
QS (querySuggest) 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 Note that if you set another field than the two default ones ( |
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
andoriginLevel2
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": "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 |
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
anduserGroups
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.
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
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.
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)
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 |
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
andc_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 |
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
andc_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
|
You want your QS model to reformat the following query suggestions:
-
5551234567
to become555-123-4567
-
abc123
to become1a2b3c
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.
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 |
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
anduserGroups
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.
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.
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.
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.
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)
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 Note that if you set another field than the two default ones ( |
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
andoriginLevel2
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": "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
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.
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.
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.
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.
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)
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 Note that if you set another field than the two default ones ( |
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:
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
andoriginLevel2
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:
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 |
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:
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
anduserGroups
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.
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:
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
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.
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.
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 ( |
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 |
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:
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
andc_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 |
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:
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
andc_context_contact_primary_role
dimension keys from its learning process.
QS (querySuggest) 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 Note that if you set another field than the two default ones ( |
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:
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
andoriginLevel2
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:
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 |
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:
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
anduserGroups
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.
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
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.
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)
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 |
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:
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
andc_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 |
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:
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
andc_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
|
You want your QS model to reformat the following query suggestions:
-
5551234567
to become555-123-4567
-
abc123
to become1a2b3c
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.
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 |
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:
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
anduserGroups
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.
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
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.
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.
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)
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 Note that if you set another field than the two default ones ( |
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:
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
andoriginLevel2
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:
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
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.
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
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.
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.
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.
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
andjohndoe@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]
.
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.
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 ( |
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]
.
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 |
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]
.
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]
.
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 |
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
|
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 additionaluserContextFields
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 |
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
.
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 theq
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]
.
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
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 |
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]
.
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]
.
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
.
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
|
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 additionaluserContextFields
dimension.