Create and Manage a Query Suggestions (QS) Model

Coveo Machine Learning (Coveo ML) Query Suggestions (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 usage analytics data for the search hub on which you want to activate Query Suggestions (QS) (see Coveo Usage Analytics Overview).

QS models are based on Coveo usage analytics data, so if no data is available, there will be no suggestions. If you recently started collecting usage analytics 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 is enough usage analytics data to return relevant query suggestions. You can review which queries logged by Coveo Usage Analytics (Coveo UA) match minimal QS requirements (see Reviewing Coveo Machine Learning Query Suggestion Candidates).

Create a QS Model

  1. On the Models (platform-eu | platform-au) page, in the upper-right corner, click Add Model to open the Add a Machine Learning Model panel.

  2. Under Name, enter a meaningful display name for the model.

  3. Under Model type, select Query Suggestions, and then click Next.

  4. (Optional) In the Learning Interval section, change the default and recommended Frequency and Data period values, and then click Next.

  5. (Optional) In the Learn From section, add filters to refine the data that the model uses to make its recommendations.

  6. Click Add Model.

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

    Note

    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.

  8. (Optional) If you want to specify advanced parameters for your model, you can use the Advanced tab of the model configuration.

  9. You can then associate the model with a pipeline to take advantage of the model in a search interface and test your model to ensure that 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

  1. On the Models (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) In the Learning Interval section, change the Frequency and Data period values.

  5. (Optional) In the Learn From section, add filters to refine the data that the model uses to make its recommendations.

  6. Click Save.

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

    Note

    The model value will change to Active when the model edition 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.

  8. You can then associate the model with a pipeline to take advantage of the model in a search interface and test your model to ensure that it behaves as expected.

    Important

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

Create a QS Model With JSON

Advanced users who are members of the Administrators and Relevance Managers built-in groups may want to create a model using a JSON configuration.

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

  2. On the right side of the page, click menu-button, and then select Add model with JSON.

  3. In the Add a Model With JSON panel that appears, select Model configuration, and then modify the model placeholder configuration:

    {
        "engineId": "querysuggest",
        "modelName": "<MODEL_NAME>",
        "modelDisplayName": "<MODEL_DISPLAY_NAME>",
        "exportPeriod": "<EXPORT_PERIOD>",
        "intervalTime": <INTERVAL_TIME>,
        "intervalUnit": "<INTERVAL_UNIT>"
    }

    Where:

    • modelName (string, required) is the name of the model, which must be unique in your Coveo organization.

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

    • exportPeriod (ISO-8601 string, required) is the period defining the age of the usage analytics data used to build the model. Must be in the ISO8601 period format (e.g., 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 (e.g., 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.

  4. Click Add Model.

    The model now appears on the Models (platform-eu | platform-au) page.

Notes
  • The default configuration contains all the required parameters with placeholder values.

  • You can add other advanced model parameters.

  • When using an existing configuration as a starting point, make sure to change the modelDisplayName as it must be unique in a Coveo organization.

Edit a QS Model JSON Configuration

  1. Access the Models (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, select Model configuration, and then modify the existing model configuration:

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

    Where:

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

    • exportPeriod (ISO-8601 string, required) is the period defining the age of the usage analytics data used to build the model. Must be in the ISO8601 period format (i.e., 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 (i.e., 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.

    • commandLineParameters (array of string) are additional parameters used to tailor the model to your use case (see Custom Model Parameters).

    • 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 (i.e., 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.

  4. Click Save to apply your changes.

Delete a QS Model

Important

You must dissociate a model from all its associated query pipelines before deleting it. Models aren’t automatically dissociated from pipelines when they’re deleted.

  1. On the Models (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 Delete a Model panel that appears, click Delete model.

Review Active Model Information

On the Models (platform-eu | platform-au) page, click the desired model (must be Active), and then click Open in the Action bar (see Reviewing Coveo Machine Learning Model Information).

Reference

QS Models Reference

Default number of suggestions: 10

The JavaScript Search Framework’s Omnibox component overrides this value at query time with its own default of 5 (see numberOfSuggestions option). Therefore, in a JavaScript Search Framework-powered search interface, a maximum of 5 (not 10) query suggestions is recommended by default.

"Status" Column

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

When inspecting the Status column, a given model is either in the Active or Inactive state. Additional information can be displayed depending on the model’s current state.

status column

The following table lists the possible model statuses, their definitions, and their status colors as shown in the Administration Console:

Status Definition Status color

Active

The model is active and available.

green

Inactive

The model isn’t available.

grey

Update in queue

Waiting to process a scheduled update or configuration change.

green

Updating

The model is being rebuilt based on a new configuration.

green

Waiting

The model is in the building queue.

blue

Building

The model is currently being processed.

blue

Degraded

The model is active, but has some limitations. Additional information is available in the Error section of a model (see Review Coveo Machine Learning Model Information).

orange

Failed

The model couldn’t be built with the requested configuration. Additional information is available in the Error section of a model (see Review Coveo Machine Learning Model Information). See Edit a QS Model for information on how to edit a model configuration.

red

Update failed

The model couldn’t be updated with the requested configuration.

red

Error

An error prevented the model from being built successfully.

grey

“Learning Interval” Section

In this section, you can modify the following:

  • Frequency: The rate at which the model is retrained.

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

The more data is available for the model to learn from, the better will be the recommendations. As a general guide, a usage analytics data set of 10,000 queries or more typically allows a Coveo ML model to provide very relevant recommendations. You can look at your Coveo Usage Analytics (Coveo UA) 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 is regularly retrained on a more recent Coveo UA data set, to ensure that recent user behavior is learned and that the model freshness maintained.

Set your Coveo ML model training Frequency parameter in relation with the Data Period value. Select a longer time interval for a larger Data Period and a shorter time interval for a smaller Data Period as recommended (√) in the following table.

Data Period

Frequency

Daily

Weekly

Monthly

1 month

check

check

3 months (Recommended)

check

6 months

check

Notes
  • Because very frequently retraining a model based on a long period would have very little effect and consume significant Coveo ML service resources, some Data Period and training Frequency parameter value combinations aren’t allowed.

  • If your Coveo organization has not yet collected enough data according to requirements, but your search interface has more than 55 visits per day in which a user query is followed by a click for a specific language, you can reproduce the following configuration depending on when you start collecting data:

    Data collected for Data Period Frequency
    Daily Weekly Monthly
    1 to 29 days 1 month check
    1 month 3 months check

“Learn From” Section

The Learn From section allows you to refine the data that the model uses to make its recommendations. By narrowing down the set of data 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 (i.e., 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.

To add a filter:

  1. Click Add-Filter.

  2. In the Select a dimension drop-down menu, select the dimension on which you want to base the learning of the model.

  3. In the Select an operator drop-down menu, select the appropriate operator.

  4. In the Select value(s) drop-down menu, add, type, or select the appropriate value.

  5. Click Add Filter.

Required Privileges

By default, members of the Administrators and Relevance Managers built-in groups can view and edit elements of the Models (platform-eu | platform-au) page.

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