Create search configurations

This is for:

Developer

In this article

Manage search pages using the Coveo Merchandising Hub
Using the search configuration endpoints
Conflict between global and specific configurations
Using rule operators

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:

Through the Coveo Merchandising Hub
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>", 
  "name": "GLOBAL",
  "conditions": [], 
  "queryConfiguration": { 
      "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": { 
      "rankingRules": [],
      "filterRules": [],
      "pinRules": []
  },
  "scope": "global" 
}

	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.
	`conditions` allow you to specify the conditions under which this configuration should be applied. For the global configuration, these are left empty.
	`queryConfiguration` allows you to specify which facets, sort criteria, and additional fields you want to be returned for this configuration.
	`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.
	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": [ 
      {
          "operator": "isExactly",
          "values": [
              "surfboard"
          ]
      }
  ],
  "queryConfiguration": {}, 
  "rules": { 
      "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" 
}

	`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`.
	`queryConfiguration` is left empty, which means this global configuration of this property will be applied as the default.
	`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.
	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.

Using rule operators

There’s a list of predefined operators that merchandisers can use to scope rules to products whose attributes meet specific criteria.

If you’re using the Commerce API directly, you can specify rules in the JSON object that you send to the API. These rules can leverage any operator to target products based on their attributes.

For example, the following JSON showcases the use of two different operators:

{
  "trackingId": "sports",
  "conditions": [
    {
      "operator": "isExactly",
      "values": [
        "surfboard"
      ]
    }
  ],
  "queryConfiguration": {
    "additionalFields": [],
    "facets": {
      "enableIndexFacetOrdering": true,
      "freezeFacetOrder": false,
      "facets": []
    },
    "perPage": 24,
    "sorts": []
  },
  "rules": {
    "rankingRules": [ 
      {
        "filters": [
          {
            "fieldName": "ec_brand",
            "operator": "contains",
            "value": {
              "type": "array",
              "values": [
                "Barca"
              ]
            }
          }
        ],
        "value": 345,
        "action": "boost", 
        "name": "Boost Barca brand"
      }
    ],
    "filterRules": [ 
      {
        "filters": [
          {
            "fieldName": "cat_color",
            "operator": "isExactly",
            "value": {
              "type": "array",
              "values": [
                "Lime"
              ]
            }
          }
        ],
        "action": "exclude", 
        "name": "Exclude Lime!"
      }
    ],
    "pinRules": []
  },
  "scope": "specific"
}

	Create a `rankingRules` object that leverages the `contains` operator to boost products with the `ec_brand` attribute containing `Barca`.
	Specify the action to take when the rule is met. Ranking rules can have either `boost` or `bury` actions. Here, the products are boosted.
	Create a `filterRules` object that uses the `isExactly` operator to exclude products with the `cat_color` attribute set to `Lime`.
	Define the action to take when the rule is met. Filter rules can either `include` or `exclude` products. In this case, the products are excuded.

For a complete mapping of operator names to their Commerce API syntax, see the following table:

Operator Commerce API syntax

Operator	Commerce API syntax
Is	`isExactly`
Is not	`isExactlyNot`
Contains	`contains`
Does not contain	`doesNotContain`
Is defined	`isDefined`
Is not defined	`isNotDefined`
Is greater than (>)¹	`isGreaterThan`
Is less than (<)¹	`isLessThan`
Is greater than or equal to (≥)¹	`isGreaterThanOrEqualTo`
Is less than or equal to (≤)¹	`isLessThanOrEqualTo`

isExactly

isExactlyNot

contains

doesNotContain

isDefined

isNotDefined