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 commerce catalog and then delves into tuning query pipeline components to further improve the relevance of your solution in the context of Coveo for Commerce.

Query your commerce catalog content

In most cases, you’ll want queries originating from a given ecommerce search interface to target a specific catalog 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, and ensure that searches performed on that page are logged in usage analytics.


Before proceeding, you must:

Step 1: Retrieve the catalog name

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

Access the Catalogs (platform-ca | platform-eu | platform-au) page, and then locate and copy the desired catalog 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.

The easiest way to query a catalog is to configure a query pipeline rule that transparently adds the catalog 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 name retrieved in step 1.

    3. Click Add Rule.

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

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.


The preprocessRequest method is a powerful tool, and it can be leveraged to do things that should be done in a different manner. For example, you can use it to set aq, but you should use the Headless AdvancedSearchQuery action instead. You can use them in Atomic as well.

If you have to use preprocessRequest, you should code defensively. For example, you can implement try…​catch to prevent errors.

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

  return request;
1 Replace <MY_CATALOG_NAME> with the name of your catalog.

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


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, tune query pipeline ranking weight rules roughly as follows:

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


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


Assuming you respect the leading practices, you can create query pipeline thesaurus rules for synonyms.


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 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 commerce catalog, you must mention the catalog ID of the desired catalog to associate a commerce catalog with a query pipeline. Here are some common parameters:

Commerce query parameters