Create search configurations

This is for:

Developer

While you don’t need to create a search configuration before querying products from a search interface, creating a search configuration specifies which facets, sorts, additional fields, and which rules should apply when your front-end queries the Commerce API.

There are two types of configurations: global and specific.

  • Global configuration: Define common elements that you want returned with each search, such as facets, sorting, additional fields, etc.

    The global configuration is important in the context of search because, unlike Product listing pages (PLPs), which are preconfigured based on a known set of products, search is much more responsive. It’s impossible to know what the user will query for, which means the global configuration will be leveraged for most, if not all, queries.

  • Specific configuration: Define a specific configuration when you want certain queries to have rules such as filtering out or ranking products in a certain way.

You can create or modify your search configurations in two ways:

  1. Through the Coveo Merchandising Hub

  2. Using the configuration endpoints directly (which the CMH uses under the hood)

Note

At this time, the Coveo Merchandising Hub (CMH) doesn’t let you configure facets, sorting, additional fields that should be returned with your query, or modify the global configuration.

To do this, you’ll have to call the configuration endpoints directly.

Manage search pages using the Coveo Merchandising Hub

The Coveo Merchandising Hub (CMH) allows merchandisers to manually curate the products displayed in search results via the CMH Search manager.

While Coveo ML models provide intelligent and personalized search results, the CMH lets you manually adjust the search results to meet your business needs.

For example, merchandisers can use the CMH to:

  • Promote specific products when specific queries are performed.

  • Pin promoted products to the top of search results.

  • Boost or bury products based on specific criteria.

  • Define synonyms for specific queries.

To learn more about the CMH and how to use it, see Coveo Merchandising Hub (CMH).

Using the search configuration endpoints

A search configuration is a JSON object that follows a specific format. You can modify search configurations by calling the configurations endpoints and providing a configuration JSON.

Global search configuration

Since search is responsive and it’s impossible to know what the user will query, the global configuration will be leveraged for most, if not all, queries.

Let’s take a detailed look at a sample global search configuration JSON:

{
  "trackingId": "<TRACKING ID>", 1
  "name": "GLOBAL",
  "conditions": [], 2
  "queryConfiguration": { 3
      "additionalFields": [
          "color",
          "size"
      ],
      "facets": {
          "enableIndexFacetOrdering": false,
          "freezeFacetOrder": true,
          "facets": [
              {
                  "type": "numericalRange",
                  "facetId": "ec_price",
                  "field": "ec_price",
                  "displayNames": [
                      {
                          "value": "Price",
                          "language": "en"
                      }
                  ]
              },
              {
                  "type": "regular",
                  "facetId": "cf_product_type",
                  "field": "cf_product_type",
                  "displayNames": [
                      {
                          "value": "Product Type",
                          "language": "en"
                      }
                  ]
              },
              {
                  "type": "hierarchical",
                  "facetId": "ec_category",
                  "field": "ec_category",
                  "displayNames": [
                      {
                          "value": "Category",
                          "language": "en"
                      }
                  ],
                  "delimitingCharacter": "|"
              }
          ]
      },
      "perPage": 15,
      "sorts": [
          {
              "sortCriteria": "relevance"
          },
          {
              "sortCriteria": "fields",
              "fields": [
                  {
                      "field": "ec_promo_price",
                      "direction": "desc",
                      "displayNames": [
                          {
                              "value": "Price (High to Low)",
                              "language": "en"
                          }
                      ]
                  }
              ]
          }
      ]
  },
  "rules": { 4
      "rankingRules": [],
      "filterRules": [],
      "pinRules": []
  },
  "scope": "global" 5
}
1 The trackingId allows you to segregate your configurations. When you make a request via the Commerce API to retrieve this configuration, you’ll need to specify the tracking ID to retrieve the configuration.
2 conditions allow you to specify the conditions under which this configuration should be applied. For the global configuration, these are left empty.
3 queryConfiguration allows you to specify which facets, sort criteria, and additional fields you want to be returned for this configuration.
4 rules lets you specify the ranking rules, filter rules, or pin rules you want to apply to your page. For the global configuration, we recommend you leave these empty. If you want to apply these rule on specific queries, see Specific search configuration.
5 The scope of the configuration. This can be either specific or global, indicating whether the configuration is specific to a page or shared across multiple pages.

For more details on all the possible parameters, see the reference documentation.

Specific search configuration

Once you have created a global search configuration, you can create specific configurations for when certain query conditions are met.

For example, if you want to return only blue products when the user searches for "surfboards", you can have the following configuration.

{
  "trackingId": "sports",
  "conditions": [ 1
      {
          "operator": "isExactly",
          "values": [
              "surfboard"
          ]
      }
  ],
  "queryConfiguration": {}, 2
  "rules": { 3
      "rankingRules": [],
      "filterRules": [
          {
              "name": "Blue color",
              "locales": [],
              "filters": [
                  {
                      "fieldName": "cat_color",
                      "operator": "isExactly",
                      "value": {
                          "type": "array",
                          "values": [
                              "Blue"
                          ]
                      }
                  }
              ],
              "action": "include"
          }
      ],
      "pinRules": [
          {
              "name": "Pin blue sandal",
              "locales": [],
              "rankByPermanentId": {
                  "SP04884_00002": 0
              },
              "action": "pin"
          }
      ]
  },
  "scope": "specific" 4
}
1 conditions allow you to specify the conditions under which this configuration should be applied. Here, the configuration is applied when the query is exactly surfboard.
2 queryConfiguration is left empty, which means this global configuration of this property will be applied as the default.
3 rules can be used to define which products get returned by the search query.

In this configuration, filterRules are applied to show only blue products, while pinRules ensure that a specific sandal with the ID SP04884_00002 is always the first product returned.
4 The scope of the configuration is set to specific.

For more details on all the possible parameters, see the reference documentation.

Conflict between global and specific configurations

As you can specify queryConfiguration and rules in both the global and the specific configuration, it’s important to understand how conflict is handled if they’re set in both places. Conflict resolution varies depending on the property in question.

Using queryConfiguration in both global and specific configurations

If you specify queryConfiguration in the global configuration and then omit it in a specific configuration, the global configuration will be used as a default.

If a specific configuration conflicts with a property in the global configuration, and the conditions of the specific configuration are met, then the property in the specific configuration takes precedence.

Example

Suppose you specify a numeric facet on ec_price in the global configuration and then a numeric facet on rating in a specific configuration for the "surfboards" query. The Commerce API returns the rating facet and not the ec_price facet when the user queries for "surfboards".

Using rules in both global and specific configurations

Within rules, you can’t set pinRules at all in the global configuration, but you can set rankingRules and filterRules.

For rankingRules and filterRules, if you set them in the global configuration and then omit them in a specific configuration, the global configuration will be used as a default. However, if these rules are set in both places, and a specific configuration is queried, these are merged.

Example

Suppose you boost "Blue" products in the global configuration using rankingRules. Next, you create a PLP page using filterRules to filter products that belong to the "surfboards" category. Now, when this PLP page is queried, it will return surfboards and additionally boost blue surfboards.