Create and manage a Query Suggestions (QS) model

This is for:

Developer System Administrator

Coveo Machine Learning (Coveo ML) Query Suggestion (QS) models provide end-users with relevant query completion suggestions.

To take advantage of Coveo ML QS, members with the required privileges must first create their QS models.

Prerequisites

Ensure that your Coveo organization collects data for the search hub on which you want to activate Query Suggestions (QS) (see Coveo Analytics overview).

QS models are based on Coveo Analytics data, so if no data is available, there will be no suggestions. If you recently started collecting data, suggestions will improve as more data becomes available each time the model is retrained.

When your search interface has low traffic, you may wonder if there’s enough analytics data to return relevant query suggestions. You can review which queries logged by Coveo Analytics match minimal QS requirements (see Review query suggestion candidates).

Note

To ensure optimal performance, a Query Suggestion (QS) model limits the number of possible suggestions per language to a preset maximum. The limit is enforced after the most relevant query suggestions are identified and ranked, and after any manually defined default query suggestions are applied. The enforced limit is large enough to not negatively impact the quality of the suggestions. The most relevant suggestions are always recommended to the user, regardless of the enforced limit. The limit, however, may explain why a query that appears as a candidate in your data isn’t suggested for a given user query.

Create a QS model

  1. On the Models (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console, click Add model, and then click the Query Suggestions card.

  2. Click Next.

  3. (Optional) In the Learning interval section, you can change the default and recommended values for both Data period and Building frequency.

  4. Click Next.

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

    Example

    You want your QS model to return queries that pertain to a specific user group, so you add a data filter to ensure that only a specific set of analytics are used by the model for training purposes.

    Tip

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

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

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

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

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

  6. Click Next.

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

  8. (Optional) Use the Project selector to associate your model with one or more projects.

  9. Click Start building.

    Note

    On the Models (platform-ca | platform-eu | platform-au) page, under the Status column, in the model row, the value is most probably Inactive.

    The model value will change to Active when the model creation is complete (typically within 30 minutes, depending on the amount of usage analytics data to process). The model can only return recommendations when its status is Active.

    For more information on Coveo ML model statuses, see the Status column reference.

  10. (Optional) Configure advanced settings for your model.

  11. Associate the model with a pipeline to use the model in a search interface and test your model to make sure it behaves as expected.

    Important

    Make sure to follow the model association leading practices before associating your model with your production query pipeline.

Advanced configuration

You can configure advanced settings for your model to suit specific use cases.

Some advanced settings are available from the model options in the Administration Console, while others are only available through JSON configuration parameters.

Notes

To specify advanced settings

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

  2. Do one of the following:

  1. Click Save.

Manage a QS model

You can edit using the model options or JSON, delete, or review information for your model.

Edit a QS model

  1. On the Models (platform-ca | platform-eu | platform-au) page, click the model you want to edit, and then click Edit in the Action bar.

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

  3. Under Name, you can optionally edit the model’s display name.

  4. (Optional) Use the Project selector to associate your model with one or more projects.

  5. (Optional) In the Learning interval section, you can change the default and recommended Data period and Building frequency.

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

    Example

    You want your QS model to return queries that pertain to a specific user group, so you add a data filter to ensure that only a specific set of analytics are used by the model for training purposes.

    Tip

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

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

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

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

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

  7. (Optional) Configure advanced settings for your model.

  8. Click Save.

    Note

    Some configuration changes initiate an automatic model rebuild when you save the model. The Models (platform-ca | platform-eu | platform-au) page shows your model’s current Status. Model settings take effect only when its status is Active.

    For more information on Coveo ML model statuses, see the Status column reference.

  9. Associate the model with a pipeline to use the model in a search interface and test your model to make sure it behaves as expected.

    Important

    Make sure to follow the model association leading practices before associating your model with your production query pipeline.

Edit a QS model JSON configuration

  1. Access the Models (platform-ca | platform-eu | platform-au) page.

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

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

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

    Where:

    • modelDisplayName (string) is the name of the model appearing on the Models (platform-ca | platform-eu | platform-au) page.

    • exportPeriod (ISO-8601 string, required) is the period defining the age of the Coveo Analytics data used to build the model. Must be in the ISO8601 period format (that is, PyYmMwWdDThHmMsS).

      Note

      Unless an exportOffset is specified, the exportPeriod uses the moment when the model was generated as a base.

    • intervalTime (integer, required) is the number of intervalUnit (that is, DAY, WEEK, or MONTH) between each update of the model. Must be between 1 and 30 inclusively.

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

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

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

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

      Example

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

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

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

    • extraConfig (array of string) are additional advanced parameters used to tailor the model to your use case.

  4. Click Save to apply your changes.

Delete a QS model

Note

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

  1. On the Models (platform-ca | platform-eu | platform-au) page, click the ML model that you want to delete, and then click More > Delete in the Action bar.

  2. In the panel that appears, click Delete.

Review model information

On the Models (platform-ca | platform-eu | platform-au) page, click the desired model, and then click View in the Action bar. For more information, see Reviewing model information.

Reference

QS models reference

Default number of suggestions: 10

If you build your search interface with the Atomic framework, you can change this behavior by using the maxWithQuery and maxWithoutQuery properties of the atomic-search-box-query-suggestions component.

Advanced model options

Query suggestions format

Use the Query suggestions format advanced setting to find specific patterns and reformat them in queries suggested by a QS model.

Example

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

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

Query suggestion pattern

To configure the query suggestions format parameter

  1. On the Models (platform-ca | platform-eu | platform-au) page, click the QS model for which you want to configure the query suggestions format parameter, and then click Edit in the Action bar.

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

  3. In the left menu of the Advanced tab, select Query suggestions format.

  4. Click Add item.

  5. In the Regular expression matching the pattern to find input, enter a regular expression that matches the pattern to find in query suggestions.

  6. In the Replace by input, enter a replacement pattern to apply when a query suggestion matches the regular expression entered in the Regular expression matching the pattern to find input.

  7. Click Save.

Suggestion filters

Use the Suggestion filters advanced setting to set the Coveo Analytics dimensions to be used as filters for potential suggestions.

The model filters the suggestions so that only the interaction data from events that include the specified dimensions are considered.

By default, the Search hub and Tab dimensions are selected. This means that for a query that originates from a specific tab in a search hub, only interactions recorded in the same search hub tab will be used by the model.

Example

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

  • Two Search hub values: partnerHub and techSupportHub

  • Four Tab values: all, documentation, training, and community

A total of eight possible filters will be created ( partnerHub/all, techSupportHub/all, partnerHub/documentation, etc.). This means that if a query originates from partnerHub/all, only interactions recorded in partnerHub/all will be used by the model to make suggestions for that query.

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

To configure the suggestion filters

  1. On the Models (platform-ca | platform-eu | platform-au) page, click the model that you want to modify, and then click Edit in the Action bar.

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

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

  4. Choose one of the following options:

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

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

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

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

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

        Important

        If you set a dimension other than the two default ones (Search Hub and Tab), you must also add the dimension at query time using the filters mlParameter.
        Custom filters configuration

  5. Click Save.

Test configuration mode

Note

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

Sandbox organizations typically lack the amount of usage analytics data that’s required to train a model. The Test configuration mode option lets you build a model in a sandbox organization with little or infrequent usage analytics data so you can test the model.

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

Note

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

To activate the test configuration mode

  1. On the Models (platform-ca | platform-eu | platform-au) page, click the model for which you want to activate the test configuration mode, and then click Edit in the Action bar.

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

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

  4. Select the Activate test configuration mode checkbox.

  5. Click Save.

Advanced JSON model parameters

filterFields (list of strings)

Use this parameter to set the Coveo Analytics dimensions to be used as filters for potential suggestions.

The model filters the suggestions so that only the interaction data from events that include the specified dimensions are considered.

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

Note

Given the default value of ["originLevel1", "originLevel2"], and the following implementation:

  • Two originLevel1 values: partnerHub and techSupportHub

  • Four originLevel2 values: all, documentation, training, and community

A total of eight possible filters will be created ( partnerHub/all, techSupportHub/all, partnerHub/documentation, etc.). This means that if a query originates from partnerHub/all, only interactions recorded in partnerHub/all will be used by the model to make suggestions for that query.
Important

If you set a field other than the two default ones (originLevel1 and originLevel2), you must also add the field at query time using the filters mlParameter.

To set the parameter

Access the model’s JSON editor, and then add the parameter configuration to the extraConfig object.

Example

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

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

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

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

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

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

For example:

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

To set the parameter

Access the model’s JSON editor, and then add the parameter configuration to the extraConfig object.

Example

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

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

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

automaticContextDiscovery (boolean)

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

Default: true

When set to false, the model doesn’t automatically consider user context found in data. However, it will use user context fields defined in the userContextFields parameter.

To set the parameter

Access the model’s JSON editor, and then add the parameter configuration to the extraConfig object.

Example

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

"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.

To set the parameter

Access the model’s JSON editor, and then add the parameter configuration to the extraConfig object.

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:

"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"
    }
  ]
}

"Status" column

On the Models (platform-ca | platform-eu | platform-au) page of the Administration Console, the Status column indicates the current state of your Coveo ML models.

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

Status Definition Status icon

Active

The model is active and available.

Active

Build in progress

The model is currently building.

Building

Inactive

The model isn’t ready to be queried, such as when a model was recently created or the organization is offline.
Click See more details for additional information (see Review model information).

Inactive

Limited

Build issues exist that may affect model performance.
Click See more details for additional information (see Review model information).

Limited

Soon to be archived

The model will soon be archived because it hasn’t been queried for an extended period of time.
Click Delete to remove the model.
Learn more about archived models.

Archive pending

Error

An error prevented the model from being built successfully.
If it’s a temporary system error, check back soon. Otherwise, click See more details for additional information (see Review model information).

Error

Archived

The model was archived because it hasn’t been queried for an extended period of time.
Click Delete to remove the model.
Learn more about archived models.

Archived

"Learning Interval" section

In this section, you can modify the following:

  • Data period: The usage analytics data time interval on which the model will be based.

  • Building frequency: The rate at which the model is retrained.

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

Data period

Building frequency

Daily

Weekly

Monthly

1 month

check

check

3 months (Recommended)

check

6 months

check

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

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

Note

If you’re testing the model in a sandbox environment in which very little analytics data is available to train the model, you can activate the Test configuration mode advanced option to ensure the model provides recommendations.

Required privileges

The following table indicates the privileges required to use elements of the Models page and associated panels (see Manage privileges and Privilege reference).

Action Service - Domain Required access level

View models

Machine Learning - Models
Organization - Organization
Search - Query pipelines

View

Edit models

Organization - Organization
Search - Query pipelines

View

Machine Learning - Models

Edit