Create and manage a Predictive Query Suggestion (PQS) model
Create and manage a Predictive Query Suggestion (PQS) model
This is for:
System AdministratorCoveo Machine Learning (Coveo ML) Predictive Query Suggestion (PQS) models provide end users with relevant query completion suggestions.
To take advantage of Coveo ML PQS, members with the required privileges must first create their PQS models.
Prerequisites
To be able to create a PQS model, make sure you:
-
Have product data indexed in a Catalog source.
-
Have configured a commerce catalog.
-
Make sure the search interface in which you want to integrate PQS log commerce events. More specifically, you must minimally log search, click and product detail view events.
-
Make sure tracked events send a tracking ID value. This is done when initializing the Coveo UA library.
Create a PQS model
-
Depending on whether models have already been created in your Coveo organization:
-
If your Coveo organization doesn’t contain any models, on the Models (platform-ca | platform-eu | platform-au) page, click the Predictive Query Suggestions card.
-
If your Coveo organization already contains models, on the Models (platform-ca | platform-eu | platform-au) page, click Add model, and then click the Predictive Query Suggestions card.
-
-
Click Next.
NoteIf your Coveo organization doesn’t meet the minimum requirements for PQS, a Requirements page appears that shows the missing requirements. You must resolve all missing requirements before creating a PQS model. For example, if a Coveo organization contains a commerce catalog but doesn’t track events, the Requirements page shows:
-
Under Catalog, select the commerce catalog that contains the products on which to base the predictive query suggestions.
The PQS model relies on the product vector space embedded within the commerce catalog selected at this step. Since models associated with the same catalog share the same product vector space, Coveo recommends having only one instance of a PQS model per catalog. This means that you should avoid creating additional PQS models for catalogs already associated with an existing model. Contact your Coveo Customer Success Manager (CSM) if you have any additional requirements.
-
Under Tracking IDs, select the tracking IDs used in the usage analytics events that you want to use to train the model.
ExampleIf you want to use the PQS model on your
Sports
website, select the tracking ID value used in the usage analytics events that originate from theSports
website. -
Click Next.
-
(Optional) In the Learning interval section, you can change the default and recommended Data period and Building frequency.
-
Click Next.
-
(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.
ExampleYou want your PQS 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.
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.
-
Under Apply filters on dataset, in the Select a dimension dropdown menu, select the dimension on which you want to base the learning of the model.
-
In the Select an operator dropdown menu, select the appropriate operator.
-
In the Select value(s) dropdown menu, add, type, or select the appropriate value.
-
You can optionally add other filters by clicking Add.
-
-
Click Next.
-
In the Name your model input, enter a meaningful display name for the model, and then click Start building.
NoteOn 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.
-
You can then associate the model with a pipeline to take advantage of the model in a search interface.
Make sure to follow the model association leading practices before associating your model with your production query pipeline.
Edit a PQS model
-
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.
-
On the subpage that opens, select the Configuration tab.
-
Under Name, you can optionally edit the model’s display name.
-
Under Tracking IDs, you can change the tracking IDs identifying the usage analytics events that you want to use to train the model.
ExampleIf you want to use the PQS model on your
Sports
website, select the tracking ID value used in the usage analytics events that originate from theSports
website. -
In the Learning interval section, you can change the default and recommended Data period and Building frequency.
-
(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.
ExampleYou want your PQS 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.
-
Under Apply filters on dataset, in the Select a dimension dropdown menu, select the dimension on which you want to base the learning of the model.
-
In the Select an operator dropdown menu, select the appropriate operator.
-
In the Select value(s) dropdown menu, add, type, or select the appropriate value.
-
You can optionally add other filters by clicking Add.
-
-
Click Save.
-
On the Models (platform-ca | platform-eu | platform-au) page, under the Status column, in the model row, the value is most probably Updating.
NoteThe 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.
-
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.
Make sure to follow the model association leading practices before associating your model with your production query pipeline.
Delete a PQS model
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. |
-
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.
-
In the Delete a Model panel that appears, click Delete model.
Review active model information
On the Models (platform-ca | platform-eu | platform-au) page, click the desired model (must be Active), and then click Open in the Action bar (see Reviewing model information).
Reference
PQS 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.
"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. |
|
Build in progress |
The model is currently building. |
|
Inactive |
The model isn’t ready to be queried, such as when a model was recently created or the organization is offline. |
|
Limited |
Build issues exist that may affect model performance. |
|
No query pipeline |
The model isn’t associated with a query pipeline. |
|
No case assist configuration |
The model isn’t associated with a case assist configuration. |
|
Soon to be archived |
The model will soon be archived because it hasn’t been queried for an extended period of time. |
|
Error |
An error prevented the model from being built successfully. |
|
Archived |
The model was archived because it hasn’t been queried for at least 30 days. |
|
“Learning Interval” section
In the Learning interval section, you can modify the following:
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 |
|||
3 months (Recommended) |
|||
6 months |
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 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 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
By default, members with the required privileges can view and edit elements of the Models (platform-ca | 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 |
View |
Edit models |
Organization - Organization |
View |
Machine Learning - Models |
Edit |