Manage query pipeline configurations for commerce catalog content
Manage query pipeline configurations for commerce catalog content
This is for:
System AdministratorThis 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.
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 commerce catalog content
Usually, you’ll want queries originating from a given ecommerce search interface to target a specific commerce 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 searches performed on that page are logged in usage analytics.
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.
Method 1: Use a query parameter rule (recommended)
The easiest way to query a catalog is to configure a query pipeline rule that transparently adds the catalog identifier to each query.
-
Access the Query Pipelines (platform-ca | platform-eu | platform-au) page.
-
Double-click the query pipeline used by your search interface.
-
Select the Advanced tab, and then click Query parameters.
-
In the upper-right corner, click Add query parameters rule.
-
In the Add a Query Parameter Rule panel:
-
In the Parameter name field, enter
commerce.catalogId
. -
For the String parameter type, in the Parameter value field, enter the catalog name retrieved in step 1.
-
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.
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.
In a JavaScript Search Framework interface, you would use the buildingQuery
event handler.
Recommended query pipeline configurations
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 to0
.To set the
termCorrelation
parameter, you must edit the rule’s code:-
On the Query Pipelines (platform-ca | platform-eu | platform-au) 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: -
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:
-
$splitValues
query extensions will extract query keywords. -
$removeMatchingValues
will remove irrelevant keywords, such asAND
/OR
/(
/)
, which 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:$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'))
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.
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.
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.
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 commerce catalog, you must mention the catalog ID of the desired catalog to query your commerce catalog content. Here are some common parameters: