---
title: Associate a Product Recommendation (PR) model with a query pipeline
slug: p1vg0524
canonical_url: https://docs.coveo.com/en/p1vg0524/
collection: coveo-for-commerce
source_format: adoc
---
---
conditionalContentOfType: prPipelineAssociation
---
# Associate a Product Recommendation (PR) model with a query pipeline

> **Important**
>
> Make sure to select the correct tab to view the content relevant to the context in which you're associating your Product Recommendation model:
> 
> * To associate the model to power [recommendation slots](https://docs.coveo.com/en/o9b80563/) configured through the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/), select the **Coveo Merchandising Hub** tab.
> 
> * To associate the model to power a recommendation interface that isn't configured through the CMH, select the **Generic** tab.

When a [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [model](https://docs.coveo.com/en/1012/) has been created, it must be associated with a [query pipeline](https://docs.coveo.com/en/180/) to be effective in a Coveo-powered commerce interface.

[[cmh-association,role=tab-a]]
## Associate a PR model with a pipeline serving Coveo Merchandising Hub recommendation slots

When associating a Product Recommendation model with the query pipeline for recommendations, you must configure an association for each of the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/) [recommendation strategies](https://docs.coveo.com/en/oaih0265#product-recommendation-strategies) you want to use in your [storefront](https://docs.coveo.com/en/p33g0410/).
For example, if you use the **Most purchased** and **Viewed together** CMH strategies in your storefront, you must configure an association for each of these strategies.

This process involves:

. [Creating query pipeline conditions to trigger the proper association based on the strategy used in the storefront](#step-1-create-the-query-pipeline-conditions).

. [Associating the model with the query pipeline for recommendations](#cmh-step-2).

[[cmh-step-1,role=tab-a]]
## Step 1: Create the query pipeline conditions:

You must create a [query pipeline condition](https://docs.coveo.com/en/2793/) for each of the CMH recommendation strategies you want to use in your [storefront](https://docs.coveo.com/en/p33g0410/).

The following table provides the conditions you must create based on the CMH strategy you want to use in your storefront:

[%header,cols="~,~"]
|===
|CMH strategy
|Query pipeline condition

|Viewed together
|`Recommendation is viewed_together`

|Purchased together
|`Recommendation is bought_together`

|Intent-aware
|`Recommendation is session_recommender_single_seed`

|Most viewed
|`Recommendation is popular_viewed`

|Most purchased
|`Recommendation is popular_bought`

|Recently viewed
|`Recommendation is recently_viewed`

|Recently purchased
|`Recommendation is recently_bought`

|Purchased with recently purchased
|`Recommendation is bought_with_recently_bought`

|Buy again
|`Recommendation is buy_again`
|===

> **Tip**
>
> If you have multiple recommendation slots configured with the same CMH strategy but need different underlying pipeline strategies, you must create more specific conditions that target both the CMH strategy and the slot ID.
> 
> For example, if you have two **Purchased together** CMH slots (one for product detail pages and one for cart recommendations), you'll need conditions that use this format:
> 
> * `Recommendation is bought_together and (Context[commerce-slot-id] is <SLOT_ID_1> or Tab is <SLOT_ID_1>)`
> 
> * `Recommendation is bought_together and (Context[commerce-slot-id] is <SLOT_ID_2> or Tab is <SLOT_ID_2>)`
> 
> This lets you associate different pipeline strategies (such as **Purchased together, same category** vs. **Purchased together - Cart**) while making sure the correct underlying pipeline strategy is used for each slot.
> 
> You can find the slot ID by viewing the slot configuration in the CMH.

For instructions on how to create query pipeline conditions, see [Manage query pipeline conditions](https://docs.coveo.com/en/1959/).

[[cmh-step-2,role=tab-a]]
## Step 2: Associate a Product Recommendation model with the query pipeline for recommendations:

. In the [Coveo Administration Console](https://docs.coveo.com/en/183/), access the **Query Pipelines** page.

. In the **Query Pipelines** page, click the query pipeline configured for recommendations, and then click **Edit components**.

. Click the **Machine learning** tab, and then click **Associate model**.

. Under **Model**, select the Product Recommendation model you want to associate with the query pipeline.

. Under **Condition**, select the query pipeline condition you created in [Step 1](#step-1-create-the-query-pipeline-conditions) for the CMH strategy you want to associate with the model.

. Under **Number of results**, enter the maximum number of recommendations you want the model to return.
Maximum value is `50`.

. Under **Strategy selection**, select the [product recommendation strategy](https://docs.coveo.com/en/p85e0425/) you want to use for the model association.
Refer to the following table for the mapping between CMH strategies and underlying pipeline strategies:

[%header,cols="~,~"]
|===
|CMH strategy
|Strategy to use

.3+|Viewed together
|Viewed together

|Viewed together, same category

|Viewed together, different category

.5+|Purchased together
|Purchased together

|Purchased together without fallback

|Purchased together, same category

|Purchased together, different category

|Purchased together - Cart

.3+|Intent-aware
|Intent-aware, enriched - Homepage

|Intent-aware, most viewed

|Intent-aware, most viewed, enriched

.2+|Most viewed
|Most viewed

|Most viewed, same category

.2+|Most purchased
|Most purchased

|Most purchased, same category

|Recently viewed
|Recently viewed without fallback

|Recently purchased
|Recently purchased without fallback

.2+|Purchased with recently purchased
|Purchased together with recently viewed

|Most viewed with last viewed
|===


> **Note**
>
> If a strategy is greyed out, it means that the selected model wasn't trained to support that strategy.
> You can [edit the model](https://docs.coveo.com/en/3395#latest-edit) to include the missing strategies.

. Click **Associate model**.

[[generic-leading-practices,role=tab-b]]
## Leading practices

When associating a PR model, consider the following leading practices:

* When associating a PR model which will be used to power [recommendation slots](https://docs.coveo.com/en/o9b80563/) configured through the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/), select the **Coveo Merchandising Hub** tab at the top of this article to follow the relevant instructions.

* You should have a query pipeline dedicated to product recommendations.
This pipeline must be used solely to route recommendation queries.

* PR models shouldn't be associated with pipelines that contain other model types.

[[generic-conditions,role=tab-b]]
## About query pipeline conditions

[query pipeline conditions](https://docs.coveo.com/en/2793/) route recommendation queries to the correct query pipeline and trigger the appropriate PR model association.
To route recommendation queries to this query pipeline, use the recommended [condition-based routing](https://docs.coveo.com/en/1666#condition-based-routing-recommended) mechanism.
The recommended condition to use at the query pipeline level is:

```text
Recommendation is not empty
```

This condition uses the `recommendation` query parameter of a [Search API request](https://docs.coveo.com/en/13/api-reference/search-api#tag/Search-V3/operation/searchUsingPostV3).
It ensures that any query containing this parameter is handled by your dedicated recommendations pipeline.

Next, within that pipeline, you must create a PR model association for each strategy you want to use.
The condition for each association must check for a specific value in the `recommendation` query parameter.

For example, to trigger the "Frequently bought together" association, your component might send `frequentBought` in the `recommendation` parameter.
The corresponding association condition would be:

```text
Recommendation is frequentBought
```

> **Important**
>
> The value used in an association condition (for example, `frequentBought`) is custom and must match the value sent by your recommendation component.
> 
> For example, if you're using the generic Headless [RecommendationList](https://docs.coveo.com/en/headless/latest/reference/interfaces/Recommendation.RecommendationList.html) controller, this value is what you define in the `id` option of the controller.

[[generic-associate,role=tab-b]]
## Associate a PR model

> **Important**
>
> Follow the [model association leading practices](https://docs.coveo.com/en/{leading-practices-link}#leading-practices) when associating your model with your query pipeline.

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline for which you want to associate the model, and then click **Edit components** in the Action bar.

. On the subpage that opens, select the **Machine learning** tab, and then in the upper-right corner, click **Associate model**.

. In the **Model** dropdown menu, select the desired model.

. On the right side, under **Condition**, you can select a [query pipeline condition](https://docs.coveo.com/en/2793/) in the dropdown menu or [create a new one](https://docs.coveo.com/en/1959#create-a-condition).

. Click **Associate model**.

[[generic-edit,role=tab-b]]
## Edit a PR model association

> **Important**
>
> Follow the [model association leading practices](https://docs.coveo.com/en/{leading-practices-link}#leading-practices) when associating your model with your query pipeline.

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline for which you want to edit a model association, and then click **Edit components** in the Action bar.

. On the subpage that opens, select the **Machine learning** tab, click the desired model, and then click **Edit** in the Action bar.

. On the right side, under **Condition**, you can select a [query pipeline condition](https://docs.coveo.com/en/2793/) in the dropdown menu or [create a new one](https://docs.coveo.com/en/1959#create-a-condition).

. Click **Save**.

[[generic-dissociate,role=tab-b]]
## Dissociate a model

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline from which you want to dissociate a model, and then click **Edit components** in the Action bar.

. On the subpage that opens, select the **Machine learning** tab.

. Click the model you want to dissociate from the pipeline, and then click **Dissociate** in the Action bar.

[[generic-reorder,role=tab-b]]
## Reorder model associations

The order in which [models](https://docs.coveo.com/en/1012/) appear in the query pipeline **Machine learning** tab is only relevant when multiple models of the same type are present.
If there are no duplicate model types in the list, the model order has no effect as each model will either execute or not based on its individual condition.

However, when multiple models of the same type are present, the models are evaluated sequentially from top to bottom.
The first model with a satisfied condition is executed, and all subsequent models of the same type are ignored.

To reorder model associations in a query pipeline

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline in which you want to reorder model associations, and then click **Edit components** in the Action bar.

. On the subpage that opens, select the **Machine learning** tab.

. Click the model whose position you want to change, and then use the **Move up** or **Move down** arrows in the Action bar to change the position of the model.

[[generic-reference,role=tab-b]]
## Edit a PR model association via JSON

Advanced users may want to manage a model association via a JSON configuration to specify [association parameters](https://docs.coveo.com/en/{link}) that don't fit with the parameters available in the [Administration Console](https://docs.coveo.com/en/183/).

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline for which you want to edit a model association, and then click **Edit components** in the Action bar.

. On the **Machine learning** tab, double-click the desired model.

. If the **Edit a Model Association** subpage opens in JSON view, proceed to the next step.
Otherwise, in the upper-right corner, click [dots], click **Switch to JSON view**, and then click **Switch to JSON view** in the confirmation window.

. On the **Edit a Model Association** subpage, in JSON view, tune the JSON model association configuration as needed (see [Model association parameters](https://docs.coveo.com/en/{link})).

. Click **Save**.

### Model association parameters

You can use the following parameters when creating or editing a Coveo ML pass:q,a[PR] model association.

## `id` (string)

The unique identifier of the model association (automatically generated by the Coveo Search API).

**Example**: `62579f33-a505-4d07-b77d-545aefb2eea1`

## `position` (integer [int32])

The position of the model in the order of execution (see [Reorder model associations](#reorder-model-associations)).

**Example**: `8`

## `modelId` (string)

The unique identifier of the model (see [Review model information](https://docs.coveo.com/en/1894/)).

**Example**: `c7ab60e2-e6b8-41e8-be6a-ad5c8edc662e`

## `modelDisplayName` (string)

The name of the model as selected when [creating the model](https://docs.coveo.com/en{link}).
This field is automatically filled with the name of the Coveo ML model.

**Example**: `MyModelName`

## `modelEngine` (string)

The ID of the Coveo ML model.
This field is automatically filled with the ID of the Coveo ML model.

**Example**: `pass:q,a[ecommerce]`

## `modelStatus` (string)

The [status](https://docs.coveo.com/en{link3}) of the model.
This field is automatically generated according to the current ML model status.

**Example**: `ONLINE`

## `condition` (string)

The unique identifier of the [condition](https://docs.coveo.com/en/2793/) that must be satisfied for a request to be processed by the ML model.

**Example**: `c7ab60e2-e6b8-41e8-be6a-ad5c8edc662e`

## `conditionDefinition` (string)

The QPL expression that indicates the condition defined for the model association (see [Query Pipeline Language (QPL)](https://docs.coveo.com/en/1449/)).
This field is automatically filled when a [`condition`](#condition-string) is specified.

**Example**: `when $searchHub is \"internalSearch\"`

## `cacheMaximumAge` (string)

The maximum age of cached [query](https://docs.coveo.com/en/231/) results the ML model should accept, in the [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals) format only including the seconds and milliseconds part.

For each incoming query to be processed by the ML model, if a result set for an identical previously made query is available in the cache and this result set isn't older than the specified value, the ML model makes recommendations based on that cached query result set. Otherwise, the query is executed against the index.

**Default**: `PT105`

## `locale` (string)

The locale of the current user.
Adding a `locale` parameter to a model association allows Coveo ML to provide more relevant recommendations by taking into account the user's language and regional preferences.

**Example**

The `locale` for a user in the United States would be: `en-US`.

:leveloffset!:

### Code sample

### 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 model associations
|Machine Learning - Models  
Organization - Organization  
Search - Query pipelines
|View

.2+|Edit model associations
|Organization - Organization  
Machine Learning - Models
|View

|Search - Query pipelines
|Edit
|===