---
title: Manage query pipeline configurations for commerce catalog content
slug: '3180'
canonical_url: https://docs.coveo.com/en/3180/
collection: coveo-for-commerce
source_format: adoc
---
# Manage query pipeline configurations for commerce catalog content
This article provides guidelines on how to associate a query pipeline to a [catalog entity](https://docs.coveo.com/en/3143/) and then delves into [tuning query pipeline components](https://docs.coveo.com/en/1791/) 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](https://docs.coveo.com/en/186/).
> See [Build commerce interfaces](https://docs.coveo.com/en/o4ue6279/) for documentation on how to build commerce interfaces using the Coveo for Commerce API.

## Query your catalog entity content

Usually, you'll want [queries](https://docs.coveo.com/en/231/) that originate from a given Coveo-powered commerce [search interface](https://docs.coveo.com/en/2741/) to target a specific [catalog entity](https://docs.coveo.com/en/3143/) in your [Coveo organization](https://docs.coveo.com/en/185/).
As a result, it will automatically enforce the structure of the [catalog configuration](https://docs.coveo.com/en/l5if0520/) and only display products while using the [variant and availability attributes](https://docs.coveo.com/en/3121/) for [facets](https://docs.coveo.com/en/198/).

This will properly scope the catalog entity and ensure searches performed on that page are logged in [Coveo Analytics](https://docs.coveo.com/en/182/).

> **Important**
>
> In Coveo for Commerce implementations that target the Commerce API, [storefront associations](https://docs.coveo.com/en/o48e0216/) are used to enforce a catalog entity in queries.
> 
> Therefore, the steps in this article don't apply to those implementations.

### Prerequisites

Before proceeding, you must:

. [Index your catalog data](https://docs.coveo.com/en/p48b0322/)

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

### Step 1: Retrieve the catalog entity name

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

Access the [**Catalogs**](https://platform.cloud.coveo.com/admin/#/orgid/commerce/catalogs/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/commerce/catalogs/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/commerce/catalogs/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/commerce/catalogs/)) 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.

#### Method 1: Use a query parameter rule (recommended)

The easiest way to query a catalog entity is to configure a [query pipeline](https://docs.coveo.com/en/180/) [rule](https://docs.coveo.com/en/236/) that transparently adds the catalog entity identifier to each query.

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

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

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

. Click **Add query parameters rule**.

. In the **Add a query parameter rule** panel:

.. Select **Catalog ID**, and then click **Next**.

.. Under **Catalog**, enter the catalog entity name retrieved in [step 1](#step-1-retrieve-the-catalog-entity-name).

.. 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](https://docs.coveo.com/en/atomic/latest/usage/atomic-modify-requests-responses#modify-requests) or [Headless](https://docs.coveo.com/en/headless/latest/usage/headless-modify-requests-responses#modify-requests) interface, if you would rather modify queries before sending them to the Search API, you can do so using a `preprocessRequest` argument.

**Example**

```javascript
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](https://docs.coveo.com/en/187/) interface, you would [use the `buildingQuery`](https://docs.coveo.com/en/417#querying-commerce-catalog-content) event handler.

## Recommended query pipeline configurations

> **Important**
>
> The following guidelines _don't_ replace the [Coveo ML](https://docs.coveo.com/en/1727/) models, but merely supplement them.

In the [Coveo Administration Console](https://docs.coveo.com/en/183/), in 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/)) tab, select the target [query pipeline](https://docs.coveo.com/en/180/) and navigate to the pages indicated below.

### Ranking weights

To avoid granting excessive importance to [item](https://docs.coveo.com/en/pa8f6515/) keywords that are too common or irrelevant, you must [tune query pipeline ranking weight rules](https://docs.coveo.com/en/3412/).
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`](https://docs.coveo.com/en/3412#termcorrelation) parameter to `0`.

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

. 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, select the **Advanced** tab, and then select **Ranking Weights**.

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

. Click **Edit code**.

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

![`termCorrelation` configuration in the query pipeline | Coveo](https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/term-correlation-commerce.png)

. Click **Save**.

### Ranking expressions

Use [ranking expressions](https://docs.coveo.com/en/3375/) to leverage useful [keywords](https://docs.coveo.com/en/2738/) which may have been left behind by the above ranking weights tuning.
More precisely, you'll want to boost products whose category or brand [field](https://docs.coveo.com/en/200/) 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](https://docs.coveo.com/en/1462/) are used to isolate keywords from the query:

* [`$splitValues`](https://docs.coveo.com/en/1462#splitvalues) splits the query text by any non-word character (`\s|\W`), which correctly separates words from special characters like parentheses.
* [`$removeEmptyValues`](https://docs.coveo.com/en/1462#removeemptyvalues) removes any empty strings that result from the split.
* [`$removeMatchingValues`](https://docs.coveo.com/en/1462#removematchingvalues) removes irrelevant keywords, such as `AND` or `OR`, which may appear in thesaurus expansions.

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:$removeEmptyValues(values: $splitValues(text:$query, separator:'\s|\W')))`

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

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

### Thesaurus

If you follow the [leading practices](https://docs.coveo.com/en/3405#leading-practices), you can [create query pipeline thesaurus rules](https://docs.coveo.com/en/3405/) for synonyms on the **Search terms** tab of your query pipeline.

**Example**

Your [index](https://docs.coveo.com/en/204/) contains several [items](https://docs.coveo.com/en/210/) pertaining to the unfortunately named **ACME CTRLR** game controller (user manuals, troubleshooting articles, etc.).

[Coveo Analytics](https://docs.coveo.com/en/182/) [reports](https://docs.coveo.com/en/266/) 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](https://docs.coveo.com/en/2742/) rule that includes `acme ctrlr` when `acme pad` is part of the user's query.

![Capture of the Administration Console showing a Thesaurus rule | Coveo](https://docs.coveo.com/en/assets/images/tune-relevance/acme-thesaurus.png)

### Stop words

You can leverage [stop words](https://docs.coveo.com/en/3406/) 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](https://docs.coveo.com/en/3407#test-the-relevance-of-your-stop-words).

![commerce stop words](https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/3180_images/stop-words.png)

### Query parameters

[Add query pipeline query parameters](https://docs.coveo.com/en/3411/) on the **Advanced** tab of your query pipeline to ensure the [query syntax](https://docs.coveo.com/en/1552/) is disabled and to enable [partial match](https://docs.coveo.com/en/414/).
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](#query-your-catalog-entity-content).
Here are some common parameters:

* [Enable query syntax](https://docs.coveo.com/en/3411#enable-query-syntax)

* [Partial match](https://docs.coveo.com/en/3411#partial-match)

* [Catalog ID](https://docs.coveo.com/en/3411#catalog-id)

![Coveo commerce query parameters](https://docs.coveo.com/en/assets/images/coveo-for-commerce/images/3180_images/query-parameters.png)