Associate a Product Recommendation (PR) model with a query pipeline

This is for:

System Administrator

When a Coveo Machine Learning (Coveo ML) model has been created, it must be associated with a query pipeline to be effective in a search interface.

organization members with the required privileges can access the Machine Learning tab of a query pipeline configuration page to manage Coveo ML model associations for that query pipeline.

Leading practices

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

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

  • When associating a PR model which will be used to power recommendation slots configured through the Coveo Merchandising Hub (CMH), you must configure an association for each of the available strategies in the same query pipeline.

Associate a PR model

Important

Follow the model association leading practices when associating your model with your query pipeline.
Note

When using a Coveo Headless library, ensure your query pipeline has the following condition: Recommendation is not empty.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to associate the model, and then click Edit components in the Action bar.

  2. On the subpage that opens, select the Machine Learning tab, and then in the upper-right corner, click Associate Model.

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

    Important

    PR models should not be associated with pipelines that contain other model types.

  4. On the right side, under Condition, you can select a query pipeline condition in the dropdown menu or create a new one.

  5. In the Advanced Configuration section, select the appropriate model strategy. Other association strategies are available when you associate your model via a JSON configuration.

  6. Click Associate Model.

Notes

  • When associating a PR model which will be used to power recommendation slots configured through the Coveo Merchandising Hub (CMH), repeat this process to create an association for each available strategy.

  • If the PR model is used in a Coveo for Commerce implementation that targets the Search API to generate recommendations, and that you want to use multiple strategies, you should repeat this process with the appropriate models and conditions. For more information about this process, see Use multiple PR strategies.

Edit a PR model association

Important

Follow the model association leading practices when associating your model with your query pipeline.
Note

When using a Coveo Headless library, ensure your query pipeline has the following condition: Recommendation is not empty.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to edit a model association, and then click Edit components in the Action bar.

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

  3. On the right side, under Condition, you can select a query pipeline condition in the dropdown menu or create a new one.

  4. In the Advanced Configuration section, select the appropriate model strategy. Other association strategies are available when you associate your model via a JSON configuration.

  5. Click Save.

Associate a PR model via a JSON configuration

Advanced users may want to manage a model association via a JSON configuration to specify association parameters that don’t fit with the parameters available in the Administration Console.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to associate a model, and then click Edit components in the Action bar.

  2. On the subpage that opens, select the Machine Learning tab, and then in the upper-right corner, click dots, and select Associate a model in JSON view.

  3. On the Associate a Model subpage, in JSON view, replace the <Model_ID> placeholder with the actual ID of the model you want to associate with the pipeline (see Review model information).

    Note

    Once you have accessed the Associate a Model subpage in JSON view:

    • You can always go back to the Associate a Model subpage in the UI view and use the available options. However, all unsaved changes made on the Associate a Model subpage in JSON view will be lost.

    • The Associate a Model subpage in JSON view becomes the default model association view for that model. In other words, the Associate a Model subpage in JSON view is now automatically displayed when you access this model association.

  4. Click Associate Model.

Edit a PR model association via a JSON configuration

Advanced users may want to manage a model association via a JSON configuration to specify association parameters that don’t fit with the parameters available in the Administration Console.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to edit a model association, and then click Edit components in the Action bar.

  2. In the Machine Learning tab, click the desired model, and then click Edit in the Action bar.

  3. On the Edit a Model Association subpage, click dots, and then select Switch to JSON view.

  4. On the Switch to JSON view? panel that appears, click Switch to JSON view.

    Important

    Switching to the JSON view of the Edit a Model Association subpage cancels unsaved configuration changes made on the Model Association page.

  5. On the Edit a Model Association subpage, in JSON view, tune the JSON model association configuration as needed (see Model association parameters).

    Note

    Once you have accessed the Associate a Model subpage in JSON view:

    • You can always go back to the Edit a Model Association subpage in the UI view and use the available options. However, all unsaved changes made on the Associate a Model subpage in JSON view will be lost.

    • If you specified non-default parameters in JSON view of the Edit a Model Association subpage, the complete configuration will be reset to the default one when switching back to the UI view of the Edit a Model Association subpage.

    • The Edit a Model Association subpage in JSON view becomes the default model association view for that model. In other words, the Edit a Model Association subpage in JSON view is now automatically displayed when you access this model association.

  6. Click Save.

Dissociate a model

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline from which you want to dissociate a model, and then click Edit components in the Action bar.

  2. On the subpage that opens, select the Machine Learning tab.

  3. In the Machine Learning tab, click the model you want to dissociate from the pipeline, and then click Dissociate in the Action bar.

Reorder model associations

The Coveo ML models of a given type are executed in the order in which they appear on the page until a condition is satisfied.

Important

The first model on the list will be used if no conditions are met.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline in which you want to reorder model associations, and then click Edit components in the Action bar.

  2. On the subpage that opens, select the Machine Learning tab.

  3. In the Machine Learning tab of the desired query pipeline, 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.

Reference

PR advanced configuration options (strategies)

When associating a PR model with a query pipeline, you must select a recommendation strategy to adapt the suggested items based on your use case.

This table shows the usage analytics events required to get the most of each strategy, along with the location in which each strategy can be leveraged in an ecommerce interface. Note that this table only lists the strategies that are available in the Advanced Configuration section of the model association panel.

Recommendation strategy Recommended location Required events Optional events

Cart recommender (cart)

Cart page

detail

purchase

None

Frequently bought together (frequentBought)

Product display page (PDP)

purchase

add (to cart)

remove (from cart)

Frequently viewed together (frequentViewed)

Product detail page

detail

click

Popular items (Bought) (popularBought)

Home page / No results page

purchase

None

Popular items (Viewed) (popularViewed)

Home page / No results page

detail

click

User recommender (user)

Home page

detail

purchase

add (to cart)

remove (from cart)

User recommender

When leveraging the User recommender strategy, the model suggests products to the current user based on their general interests. To achieve this, the model learns from users' previous actions, and uses this information to find other customers that share similar browsing patterns. The model then suggests products that have been previously browsed by customers who share similar interests with the current user.

Frequently bought together

When leveraging the Frequently bought together strategy, the model suggests products frequently bought with the current product based on purchases made by other users. In other words, the model analyzes the items that customers often buy together with the product that the user is currently viewing.

Note that when a Coveo ML PR model leveraging the Frequently bought together strategy doesn’t generate enough recommendations, the model will use the Frequently bought together in different categories, Frequently viewed together, or Popular items (bought) strategies to ensure that recommendations are displayed to the end user.

Example

As a user of an electronics retailer ecommerce website, you’re currently viewing a gaming computer. Based on other customers' purchase history, the model suggests gaming mice and keyboards that were bought together with the computer you’re currently viewing.

Note

This strategy requires an item to be passed in the itemId parameter of the mlParameters object of the related query to the Search API.

Frequently bought together in same category

When leveraging the frequentBoughtSameCategory strategy, the model recommends the most frequently purchased products in the same category as the item the user is currently viewing.

Note that when a Coveo ML PR model leveraging the Frequently bought together in same category strategy doesn’t generate enough recommendations, the model will use the Frequently bought together, or Popular items (bought) strategies to ensure that recommendations are displayed to the end user.

Example

As a user of an electronics retailer ecommerce website, you’re currently viewing a pair of headphones whose category value is headphones.

Since the product page incorporates a recommendations interface that leverages the frequentBoughtSameCategory strategy, the recommended products are the items from the headphones category that have been purchased the most with the item you’re currently viewing.

Important

The frequentBoughtSameCategory strategy can’t be selected from the Coveo Administration Console when associating a Coveo ML PR model with a query pipeline.

To use the frequentBoughtSameCategory strategy in your query pipeline, you must associate your model via a JSON configuration.
Note

This strategy requires an item to be passed in the itemId parameter of the mlParameters object of the related query to the Search API.

Frequently bought together in different categories

When leveraging the frequentBoughtDifferentCategory strategy, the model recommends the products that have been purchased the most with the product that the user is currently viewing. The recommendations are filtered to show products that have a different category than the one the user is currently viewing.

Note that when a Coveo ML PR model leveraging the Frequently bought together in different categories strategy doesn’t generate enough recommendations, the model will use the Frequently bought together, or Popular items (bought) strategies to ensure that recommendations are displayed to the end user.

Example

As a user of an electronics retailer ecommerce website, you’re currently viewing a gaming computer whose category value is computer.

Since the product page incorporates a recommendations interface that leverages the frequentBoughtDifferentCategory strategy, the recommended products are the items that have been purchased the most with the computer you’re currently viewing, but that doesn’t have computer as the category value.

Important

The frequentBoughtDifferentCategory strategy can’t be selected from the Coveo Administration Console when associating a Coveo ML PR model with a query pipeline.

To use the frequentBoughtDifferentCategory strategy in your query pipeline, you must associate your model via a JSON configuration.
Note

This strategy requires an item to be passed in the itemId parameter of the mlParameters object of the related query to the Search API.

Frequently viewed together

When leveraging the Frequently viewed together strategy, the model suggests items related to each of the current products based on other users' interactions with your Coveo-powered ecommerce site in a single visit. Therefore, this strategy analyzes users' navigation behavior to provide the user with a selection of similar products that are often seen together in a single shopping session.

Note that when a Coveo ML PR model leveraging the Frequently viewed together strategy doesn’t generate enough recommendations, the model will use the Popular items (viewed) strategy to ensure that recommendations are displayed to the end user.

Example

As a user of an electronic retailer ecommerce website, you’re currently viewing the ABC gaming computer. Based on the interactions made by other users that have browsed the same computer in their shopping session, the model suggests products that have frequently been seen together with that computer in the same shopping session.

Since other users have also browsed the 123 and DEF computers along with the ABC gaming computer that you’re currently viewing, the model suggests these computers to you.

Note

This strategy requires an item to be passed in the itemId parameter of the mlParameters object of the related query to the Search API.

Frequently viewed together in the same category

When leveraging the frequentViewedSameCategory strategy, the model recommends the most frequently viewed products in the same category as the item the user is currently viewing.

Note that when a Coveo ML PR model leveraging the Frequently viewed together in the same category strategy doesn’t generate enough recommendations, the model will use the Frequently viewed together, or Popular items (viewed) strategies to ensure that recommendations are displayed to the end user.

Example

As a user of an electronics retailer ecommerce website, you’re currently viewing a pair of headphones whose category value is headphones.

Since the product page incorporates a recommendations interface that leverages the frequentViewedSameCategory strategy, the recommended products are the items from the headphones category that have been viewed the most with the item you’re currently viewing.

Important

The frequentViewedSameCategory strategy can’t be selected from the Coveo Administration Console when associating a Coveo ML PR model with a query pipeline.

To use the frequentViewedSameCategory strategy in your query pipeline, you must associate your model via a JSON configuration.
Note

This strategy requires an item to be passed in the itemId parameter of the mlParameters object of the related query to the Search API.

Frequently viewed together in different categories

When leveraging the frequentViewedDifferentCategory strategy, the model recommends the products that have been viewed the most with the product that the user is currently viewing. The recommendations are filtered to show products that have a different category than the one the user is currently viewing.

Note that when a Coveo ML PR model leveraging the Frequently viewed together in different categories strategy doesn’t generate enough recommendations, the model will use the Frequently viewed together, or Popular items (viewed) strategies to ensure that recommendations are displayed to the end user.

Example

As a user of an electronics retailer ecommerce website, you’re currently viewing a gaming computer whose category value is computer.

Since the product page incorporates a recommendations interface that leverages the frequentViewedDifferentCategory strategy, the recommended products are the items that have been viewed the most with the computer you’re currently viewing, but that doesn’t have computer as the category value.

Important

The frequentViewedDifferentCategory strategy can’t be selected from the Coveo Administration Console when associating a Coveo ML PR model with a query pipeline.

To use the frequentViewedDifferentCategory strategy in your query pipeline, you must associate your model via a JSON configuration.
Note

This strategy requires an item to be passed in the itemId parameter of the mlParameters object of the related query to the Search API.

Cart recommender

When leveraging the Cart recommender strategy, the model analyzes frequent buying patterns by grouping sets of products that are frequently purchased together in the same shopping cart.

Based on the products in a given cart, the model recommends other products that were frequently purchased together in previous similar carts. This strategy is ideal for cross-selling items on a shopping cart interface.

Example

As a user of an electronics retailer website, you view your cart which contains a TV stand and a multi-plug outlet extender. Based on other customers' purchase history, the model will suggest other TV accessories, such as HDMI cables, that were bought together with the same TV stand and outlet extender you have in your cart.

Note

This strategy requires items to be passed in the itemIds parameter of the mlParameters object of the related query to the Search API.

When leveraging the Popular items (bought) strategy, the model recommends the most purchased products.

Its usage applies a time discount, so that newer events are always more relevant. This attempts at picking up timely trends.

This strategy is useful when you want to display recommendations on a landing page. It’s also used as a backup solution for other strategies when they didn’t gather enough data to provide relevant recommendations.

When leveraging the Popular items (viewed) strategy, the model recommends the most viewed products.

Its usage applies a time discount, so that newer events are always more relevant. This attempts at picking up timely trends.

This strategy is useful when you want to display recommendations on a landing page and also used as a backup solution for other strategies when they didn’t gather enough data to provide relevant recommendations.

When leveraging the popularBoughtSameCategory strategy, the model recommends the most purchased products in the same category as the item the user is currently viewing.

This strategy is useful as a backup solution for other strategies when they didn’t gather enough data to provide relevant recommendations.

Important

The popularBoughtSameCategory strategy can’t be selected from the Coveo Administration Console when associating a Coveo ML PR model with a query pipeline.

To use the popularBoughtSameCategory strategy in your query pipeline, you must associate your model via a JSON configuration.
Note

This strategy requires an item to be passed in the itemId parameter of the mlParameters object of the related query to the Search API.

When leveraging the popularViewedSameCategory strategy, the model recommends the most viewed products in the same category as the item the user is currently viewing.

This strategy is useful as a backup solution for other strategies when they didn’t gather enough data to provide relevant recommendations.

Important

The popularViewedSameCategory strategy can’t be selected from the Coveo Administration Console when associating a Coveo ML PR model with a query pipeline.

To use the popularViewedSameCategory strategy in your query pipeline, you must associate your model via a JSON configuration.
Note

This strategy requires an item to be passed in the itemId parameter of the mlParameters object of the related query to the Search API.

Recently viewed

When leveraging the recentlyViewed strategy, the model analyzes the user’s action history to recommend items recently viewed by the user.

Important

The recentlyViewed strategy can’t be selected from the Coveo Administration Console when associating a Coveo ML PR model with a query pipeline.

To use the recentlyViewed strategy in your query pipeline, you must associate your model via a JSON configuration.

Recommendations using recently viewed

When leveraging the recommendationsUsingRecentlyViewed strategy, the model recommends products that have been viewed frequently by other users along with the products that the current user viewed during their current and previous shopping sessions.

This is useful for exposing the current user to products that other users with similar shopping behavior have also viewed during their visit.

Example

As a user of a Coveo-powered ecommerce website, you browsed the following products during your current visit:

  • ACME-800 winter boots

  • ACME-2525 ski jacket

  • ACME-33 winter hat

After viewing these products, you come back to the home page which incorporates a recommendations interface that leverages the recommendationsUsingRecentlyViewed strategy.

Based on other user sessions where the products listed above were also seen, the model recommends the following products:

  • ACME-932 winter gloves

  • ACME-1071 neck warmer

  • ACME-722 thermal socks

These products are recommended because they have been viewed frequently by other users who have also seen the products you viewed during your shopping session.

Important

The recommendationsUsingRecentlyViewed strategy can’t be selected from the Coveo Administration Console when associating a Coveo ML PR model with a query pipeline.

To use the recommendationsUsingRecentlyViewed strategy in your query pipeline, you must associate your model via a JSON configuration.

Session recommendations

The sessionRecommender strategy leverages product embedding techniques to recommend products for which the representation vectors are similar to:

  • The representation vectors of the products previously seen by the user during their shopping session.

  • The representation vector of the product the user is currently viewing.

This allows you to maximize discovery of your product inventory by showcasing products relevant to the shopper’s journey.

Example

As a user of an ecommerce website, you’re browsing multiple products during a single visit.

After viewing several products, you access the home page.

Since the home page incorporates a recommendations interface that leverages the sessionRecommender strategy, the recommended products are those for which representation vectors are similar to those of the products you browsed during your visit.

Important

The sessionRecommender strategy can’t be selected from the Coveo Administration Console when associating a Coveo ML PR model with a query pipeline.

To use the sessionRecommender strategy in your query pipeline, you must associate your model via a JSON configuration.
Note

This strategy provides better outputs when items are passed in the itemIds parameter of the mlParameters object of the related query to the Search API.

Recently bought

When leveraging the recentlyBought strategy, the model analyzes the user’s action history to recommend products that the user has recently purchased.

Important

The recentlyBought strategy can’t be selected from the Coveo Administration Console when associating a Coveo ML PR model with a query pipeline.

To use the recentlyBought strategy in your query pipeline, you must associate your model via a JSON configuration.

Recommendations using recently bought

When leveraging the recommendationsUsingRecentlyBought strategy, the model recommends products that have been purchased frequently by other users along with the products the current user purchased during their current and previous shopping sessions.

This is useful for exposing the current user to products that other users with similar shopping behavior ended up buying during their visit.

Example

As a user of a Coveo-powered ecommerce website, you previously purchased the following products:

  • ACME-800 winter boots

  • ACME-2525 ski jacket

  • ACME-33 winter hat

The site’s home page incorporates a recommendations interface that leverages the recommendationsUsingRecentlyBought strategy.

Based on other user sessions where the products listed above were also purchased, the model recommends the following products:

  • ACME-932 winter gloves

  • ACME-1071 neck warmer

  • ACME-722 thermal socks

These products are recommended because they have been purchased frequently by other users who have also bought the products you purchased.

Important

The recommendationsUsingRecentlyBought strategy can’t be selected from the Coveo Administration Console when associating a Coveo ML PR model with a query pipeline.

To use the recommendationsUsingRecentlyBought strategy in your query pipeline, you must associate your model via a JSON configuration.

Buy again

When leveraging the buyAgain strategy, the model calculates the visitors' tendency to repurchase certain products within a given time frame.

To achieve this, the model analyzes the visitor’s action history to identify previous purchases. It then checks the category of the purchased products to recognize items with a high likelihood of being repurchased.

Example

As a user of an ecommerce pet store, you previously bought a bag of dog food and a dog cage.

The model recognizes that products of the dog-food category are often repurchased, while those in the dog-cage category aren’t.

Since the website incorporates a recommendations interface that leverages the buyAgain strategy, the model recommends previously purchased products from the dog-food category because of their likelihood to be repurchased.

Important

The buyAgain strategy can’t be selected from the Coveo Administration Console when associating a Coveo ML PR model with a query pipeline.

To use the buyAgain strategy in your query pipeline, you must associate your model via a JSON configuration.
Note

If items are passed in the itemIds parameter of the mlParameters object in the related query to the Search API, these items are considered as previously purchased by the visitor.

Model association parameters

You can use the following parameters when creating or editing a Coveo ML 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).

Example: 8

modelId (string)

The unique identifier of the model (see Review model information).

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

modelDisplayName (string)

The name of the model as selected when creating the model. 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: ecommerce

modelStatus (string)

The status 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 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)). This field is automatically filled when a condition is specified.

Example: when $searchHub is \"internalSearch\"

cacheMaximumAge (string)

The maximum age of cached query results the ML model should accept, in the ISO-8601 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.

rankingModifier (integer [int32])

The ranking score modifier the ML model should apply to each item it recommends.

Default: 0

exclusive (boolean)

Whether the Search API should only return items which were recommended by the ML model, even if other items matching the query were found in the index.

Default: true

customQueryParameters (JValue (object))

A JSON object representing the additional parameters to send to Coveo ML on all queries.

This object allows you to specify the strategy used by the model.

strategy (string)

The strategy used by the model to provide its recommendations.

Available options:

Default: popularViewed

maxRecommendations (integer [int32])

The maximum number of recommendations the ML model should return.

Default: 5

Note

The maxRecommendations parameter value indicates the maximum number of recommendations that the model returns before the Coveo Search API and the index apply subsequent filters (for example, query pipeline rules or item permission).

For example, a query pipeline containing a recommendation model can be configured to return five recommendations. Since some of the items that the model can recommend are not accessible to the user or have been filtered out by a query pipeline rule, the user sees only three recommended documents.

Setting maxRecommendations to a higher value lets the model query for more items, ensuring that the user obtains the expected number of recommendations.

useAdvancedConfiguration (boolean)

Whether the model association specifies an advanced configuration.

Default: false

Code sample

The following code sample shows a Product Recommendation (PR) model association in JSON:

{
  "position": 1,
  "modelId": "XXXXXX_ecommerce_XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
  "condition": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "exclusive": true,
  "customQueryParameters": {
    "strategy": "popularViewed"
  },
  "useAdvancedConfiguration": false
}

For complete information on PR model available association parameters, see PR model association parameters reference.

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 model associations

Machine Learning - Models
Organization - Organization
Search - Query pipelines

View

Edit model associations

Organization - Organization
Machine Learning - Models

View

Search - Query pipelines

Edit