---
title: Create and manage a Predictive Query Suggestion (PQS) model
slug: lcfi0103
canonical_url: https://docs.coveo.com/en/lcfi0103/
collection: coveo-for-commerce
source_format: adoc
---
# Create and manage a Predictive Query Suggestion (PQS) model

[Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [Predictive Query Suggestion (PQS)](https://docs.coveo.com/en/m1ol5526/) [models](https://docs.coveo.com/en/1012/) provide end users with relevant query completion suggestions.

To take advantage of Coveo ML PQS, members with the [required privileges](#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](https://docs.coveo.com/en/n8of0593/).

* Have configured a [catalog entity](https://docs.coveo.com/en/3139/).

* Ensure that the [search interface](https://docs.coveo.com/en/2741/) where you want to integrate the model is configured to log [commerce events](https://docs.coveo.com/en/3188/).
More specifically, you must minimally log [click](https://docs.coveo.com/en/o1n92447/) and [product view](https://docs.coveo.com/en/o1n93101/) events.
Note that if your Coveo for Commerce implementation targets the Search API, you must also [log search events](https://docs.coveo.com/en/o1n91392/).

* Make sure tracked events send a [tracking ID](https://docs.coveo.com/en/o8rb0139/) value.
This is done when [initializing the Relay library](https://docs.coveo.com/en/o1n90002/).

PQS models are based on 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](https://docs.coveo.com/en/1012/) is [retrained](https://docs.coveo.com/en/1727#training-and-retraining).

## Create a PQS model

. On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page of the [Coveo Administration Console](https://docs.coveo.com/en/183/), click **Add model**, and then click the **Predictive Query Suggestions** card.

. Click **Next**.

> **Note**
>
> If your Coveo organization doesn't meet the [minimum requirements for PQS](https://docs.coveo.com/en/lcfi0103#prerequisites), 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 catalog entity but doesn't track events, the **Requirements** page shows:
> 
> ![PQS missing requirements](:https://docs.coveo.com/en/assets/images/leverage-machine-learning/pqs-iapr-missing-req.png)

. Under **Catalog**, select the [catalog entity](https://docs.coveo.com/en/3143/) that makes available the products on which to base the predictive query suggestions.

The Predictive Query Suggestions [model](https://docs.coveo.com/en/1012/) relies on the [product vector](https://docs.coveo.com/en/nbla0256/) space embedded within the [catalog entity](https://docs.coveo.com/en/3143/) selected at this step.
Since [models](https://docs.coveo.com/en/1012/) associated with the same catalog entity share the same product vector space, Coveo recommends having only one Predictive Query Suggestions model per catalog entity.
This means that you should avoid creating additional Predictive Query Suggestions models for catalog entities 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](https://docs.coveo.com/en/o8rb0139/) that identify the storefronts selling the products from the selected catalog entity.
If the catalog entity is associated with multiple tracking IDs, you can select multiple tracking IDs if you want the model to use usage analytics data from different storefronts, thus increasing the amount of data available for training.

**Example**

If you chose the `Sports` catalog entity, which is associated with the `Sports` and `Outdoor` tracking IDs, you can select both tracking IDs to have the model use usage analytics data from both storefronts.

> **Tip**
>
> Catalog entities and tracking IDs have a one-to-one relationship, which you can view on the [**Storefront associations**](https://platform.cloud.coveo.com/admin/#/orgid/commerce/storefront/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/commerce/storefront/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/commerce/storefront/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/commerce/storefront/)) page of the [Coveo Administration Console](https://docs.coveo.com/en/183/).

. Click **Next**.

. (Optional) In the [**Learning interval**](#learning-interval-section) section, you can change the default and recommended values for both **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 default, the model uses the [tracking IDs](https://docs.coveo.com/en/o8rb0139/) selected in previous steps to scope the dataset to the events recorded on these storefronts, but you can further refine the dataset by adding filters.

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 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 model's learning.

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


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

. Click **Next**.

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

. (Optional) Use the **Project** selector to associate your model with one or more [projects](https://docs.coveo.com/en/n7ef0517/).

. Click **Start building**.

> **Note**
>
> On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) 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](#status-column).

. [Associate the model with a pipeline](https://docs.coveo.com/en/lcfm0406/) to use the [model](https://docs.coveo.com/en/1012/) in a [search interface](https://docs.coveo.com/en/2741/).

> **Important**
>
> Make sure to follow the [model association leading practices](https://docs.coveo.com/en/lcfm0406#leading-practices) before associating your model with your production query pipeline.

## Manage a PQS model

You can [edit](#edit-a-pqs-model), [delete](#delete-a-pqs-model), or [review information](#review-model-information) for your [model](https://docs.coveo.com/en/1012/).

### Edit a PQS model

. On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) 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.

. (Optional) Use the **Project** selector to associate your model with one or more [projects](https://docs.coveo.com/en/n7ef0517/).

. Under **Tracking IDs**, you can change the [tracking IDs](https://docs.coveo.com/en/n8tg0567/) that you want to use to train the model, but they must still correspond to the catalog entity chosen when configuring the model.
A catalog entity and a tracking ID have a one-to-one relationship, which you can view on the [**Storefront associations**](https://platform.cloud.coveo.com/admin/#/orgid/commerce/storefront/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/commerce/storefront/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/commerce/storefront/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/commerce/storefront/)) page of the [Coveo Administration Console](https://docs.coveo.com/en/183/).

. In the [**Learning interval**](#learning-interval-section) 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 default, the model uses the [tracking IDs](https://docs.coveo.com/en/o8rb0139/) selected in previous steps to scope the dataset to the events recorded on these storefronts, but you can further refine the dataset by adding filters.

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 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 model's learning.

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


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

. Click **Save**.

> **Note**
>
> Some configuration changes initiate an automatic model rebuild when you save the model.
> The [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) 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](#status-column).

. [Associate the model with a pipeline](https://docs.coveo.com/en/lcfm0406/) to use the [model](https://docs.coveo.com/en/1012/) in a [search interface](https://docs.coveo.com/en/2741/) and [test your model](https://docs.coveo.com/en/mc2g0297#test-your-qs-model) to make sure it behaves as expected.

> **Important**
>
> Make sure to follow the [model association leading practices](https://docs.coveo.com/en/lcfm0406#leading-practices) before associating your model with your production query pipeline.

### Delete a PQS model

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

. On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page, click the ML model that you want to delete, and then click **More** > **Delete** in the Action bar.

. In the panel that appears, click **Delete**.

### Review model information

On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page, click the desired model, and then click **View** in the Action bar.
For more information, see [Reviewing model information](https://docs.coveo.com/en/1894/).

## 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`](https://static.cloud.coveo.com/atomic/v3/storybook/index.html?path=/docs/atomic-search-box-query-suggestions\--docs) component.

## "Status" column

On the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page of the [Administration Console](https://docs.coveo.com/en/183/), the **Status** column indicates the current state of your Coveo ML models.

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

[%header,cols="1,6,^.^1"]
|===
.^|Status
.^|Definition
|Status icon

|Active
|The model is active and available.
a|![Active](leverage-machine-learning/model-active.png)

|Build in progress
|The model is currently building.
a|![Building](leverage-machine-learning/model-build.png)

|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](https://docs.coveo.com/en/1894/)).
a|![Inactive](leverage-machine-learning/model-limited.png)

|Limited
|Build issues exist that may affect model performance.  
Click **See more details** for additional information (see [Review model information](https://docs.coveo.com/en/1894/)).
a|![Limited](leverage-machine-learning/model-limited.png)

|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](https://docs.coveo.com/en/mb3e0324/).
a|![Archive pending](leverage-machine-learning/model-limited.png)

|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](https://docs.coveo.com/en/1894/)).
a|![Error](leverage-machine-learning/model-error.png)

|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](https://docs.coveo.com/en/mb3e0324/).
a|![Archived](leverage-machine-learning/model-archived.png)
|===

## "Learning Interval" section

In this section, you can modify the following:

* [[data-period]]**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.

[cols="^3,^1,^1,^1"]
|===
.2+.^h|**Data period**
3+h|**Building frequency**

h|Daily
h|Weekly
h|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](https://docs.coveo.com/en/231/) or more typically allows a Coveo ML model to provide very relevant recommendations. You can look at your [Coveo Analytics](https://docs.coveo.com/en/182/) 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](https://docs.coveo.com/en/1342/) 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.

## Required privileges

By default, members with the [required privileges](https://docs.coveo.com/en/1832#required-privileges) can view and edit elements of the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page.

The following table indicates the privileges required to use elements of the **Models** page and associated panels (see [Manage privileges](https://docs.coveo.com/en/3151/) and [Privilege reference](https://docs.coveo.com/en/1707/)).

[cols="3",options="header"]
|===
|Action
|Service - Domain
|Required access level

|View models
|Machine Learning - Models  
Organization - Organization  
Search - Query pipelines
|View

.2+|Edit models
|Organization - Organization  
Search - Query pipelines
|View

|Machine Learning - Models
|Edit
|===

## What's next?

[Associate a Predictive Query Suggestion (PQS) model with a query pipeline](https://docs.coveo.com/en/lcfm0406/).