Manage query pipeline configurations for commerce catalog content

This is for:

System Administrator

This article provides guidelines on how to associate a query pipeline to a catalog entity and then delves into tuning query pipeline components to further improve the relevance of your solution in the context of Coveo for Commerce.

Important

This section provides information on how to implement search interfaces that interact with the Coveo Search API, which is no longer recommended for Coveo for Commerce implementations.

New Coveo for Commerce implementations should use the Coveo for Commerce API, which provides a more efficient and flexible way to interact with the Coveo Platform. See Build commerce interfaces for documentation on how to build commerce interfaces using the Coveo for Commerce API.

Query your catalog entity content

Usually, you’ll want queries that originate from a given Coveo-powered commerce search interface to target a specific catalog entity in your Coveo organization. As a result, it will automatically enforce the structure of the catalog configuration and only display products while using the variant and availability attributes for facets.

This will properly scope the catalog entity, and ensure searches performed on that page are logged in usage analytics.

Prerequisites

Before proceeding, you must:

  1. Index your catalog data

  2. Have a catalog entity

Step 1: Retrieve the catalog entity name

To query a given catalog entity, you must know its unique name.

Access the Catalogs (platform-ca | platform-eu | platform-au) page, and then locate and copy the desired catalog entity name from the table.

Step 2: Configure your search interface

Use one of the following methods to ensure that your search interface targets the desired catalog entity.

The easiest way to query a catalog entity is to configure a query pipeline rule that transparently adds the catalog entity identifier to each query.

  1. Access the Query Pipelines (platform-ca | platform-eu | platform-au) page.

  2. Double-click the query pipeline used by your search interface.

  3. Select the Advanced tab, and then click Query parameters.

  4. In the upper-right corner, click Add query parameters rule.

  5. In the Add a Query Parameter Rule panel:

    1. In the Parameter name field, enter commerce.catalogId.

    2. For the String parameter type, in the Parameter value field, enter the catalog entity name retrieved in step 1.

    3. Click Add Rule.

Queries originating from your search interface will now target the specified catalog entity.

Method 2: Use a preprocessRequest argument

In an Atomic or Headless interface, if you would rather modify queries before sending them to the Search API, you can do so using a preprocessRequest argument.

Example
preprocessRequest: (request, clientOrigin) => {
  if (clientOrigin === 'searchApiFetch') {
    const body = JSON.parse(request.body);
    body.commerce = {catalogId: '<MY_CATALOG_NAME>'};
    request.body = JSON.stringify(body);
  }

  return request;
},

Where you would replace <MY_CATALOG_NAME> with the name of your catalog entity.

In a JavaScript Search Framework interface, you would use the buildingQuery event handler.

Important

The following guidelines don’t replace the Coveo ML models, but merely supplement them.

In the Coveo Administration Console, in the Query Pipelines (platform-ca | platform-eu | platform-au) tab, select the target query pipeline and navigate to the pages indicated below.

Ranking weights

To avoid granting excessive importance to item keywords that are too common or irrelevant, you need to tune query pipeline ranking weight rules. To do this, first go to the Advanced tab, and then click Add Rule to add the following rules:

  • Set Item last modification, Keyword frequency, and Keyword in concepts to 0, as they aren’t required for product-related use cases.

  • If item titles aren’t distinctive and well formatted, lower Keyword in title to 4. While the title is important, we shouldn’t take it solely into account since the Keyword in summary ranking below is usually better.

  • Set Keyword in summary to 9.

  • Set Keyword proximity to 3. This decreases the importance given to how close keywords are to each other.

  • Set the termCorrelation parameter to 0.

    To set the termCorrelation parameter, you must edit the rule’s code:

    1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, select the Advanced tab, and then select Ranking Weights.

    2. Click the ranking weight rule for which you want to configure the termCorrelation parameter, and then in the Action bar, click More.

    3. Click Edit code.

    4. In the code editor that opens, add termCorrelation: 0 as follows:

      termCorrelation configuration in the query pipeline | Coveo

    5. Click Save.

Ranking expressions

Use ranking expressions to leverage useful keywords which may have been left behind by the above ranking weights tuning. More precisely, you will want to boost products whose category or brand field value matches a query keyword. If other fields contain relevant keywords which may be used in queries, boost them as well.

Example

Your items contain a ec_category field and a ec_brand field, which, as their names indicate, hold the product category and brand name. You create ranking expressions to apply a +25 ranking modifier on items whose values for those fields match query keywords.

The following query extensions in use:

The |\(|\) characters in the expression should only be used for hierarchical fields to match the | character separating categories.

You also have a color field which you decide to leverage in the same manner.

  • @ec_category=$removeMatchingValues(regex:'AND|OR|\(|\)',values:$splitValues(text: $query, separator: '\s'))

  • @ec_brand=$removeMatchingValues(regex:'AND|OR',values:$splitValues(text: $query, separator: '\s'))

  • @color=$removeMatchingValues(regex:'AND|OR',values:$splitValues(text: $query, separator: '\s'))

commerce ranking expressions

Thesaurus

Assuming you respect the leading practices, you can create query pipeline thesaurus rules for synonyms in the Search Terms tab of your query pipeline.

Example

Your index contains several items pertaining to the unfortunately named ACME CTRLR game controller (user manuals, troubleshooting articles, etc.).

usage analytics reports indicate that a sizable portion of end users who are obviously looking for information on this product in your Coveo-powered community portal are actually searching for acme pad, and not getting any relevant results.

To address the issue, you create a thesaurus rule that includes acme ctrlr when acme pad is part of the user’s query.

capture of the Administration Console showing a Thesaurus rule

Stop words

You can leverage stop words to remove certain irrelevant keywords from queries, such as to, in, of, etc. You should, however, do so carefully, and make sure to test the relevance of your solution with your stop words.

commerce stop words

Query parameters

Add query pipeline query parameters in the Advanced tab of your query pipeline to ensure the query syntax is disabled and to enable partial match. The query syntax should already be disabled by default, since most end users don’t know how to leverage it. As for the partial match feature, it allows your Commerce solution to return result list items which don’t contain all queried keywords. Also, to ensure queries target your catalog entity, you must reference the catalog ID of the desired catalog entity to query your catalog entity content. Here are some common parameters:

Commerce query parameters