Configure the order of facet values

You can configure how facets of any given dimension are sorted in refinement lists at run time.

You can sort the facet values either alphabetically, by frequency (number of matching results for each facet value), by display order (previously known as rank), or by statistical significance. In addition, these can be sorted in ascending or descending order.

To change the ordering of a facet’s values, you use a REST API to specify a sort option and, optionally, a sort order to apply to all the facet values in the facet.

The sort option determines the order of the facet values with respect to each other. The following sort options are available:

displayName or alpha (alphabetical) – Sorts facet values in alphabetical order using the facet value display name. This is the default order for the Category facet
count or freq - Sorts facet values by the number of records that are tagged to each. This is the default order for new facets and for facets other than Category and Price Range.
displayOrder or rank – Sorts facet values in the Category facet by the static value provided separately using the facet data API.
sig – Sorts facet values according to their statistical significance. For more information, see Order facet values by statistical significance.

The sort order can be either asc (ascending) or desc (descending). If you do not specify an order, the sort order is ascending for displayName and descending for count and displayOrder, by default.

In some cases, a combination of sort option and sort order can assign two or more facet values to the same location in a refinements list. To further sort the facet values in such cases, you can specify a second sort option and sort order pair.

The sort option and sort order are specified as values of the facet’s displayConfig parameter, as in the following example:

"displayConfig": {
     "sort":
        "count,desc;displayName,asc" 
},

The example above specifies that facet values first be sorted in descending order of frequency; any facet values that require further sorting are then sorted in ascending alphabetical order.

Note: You can specify any number of pairs of sort option and sort order values, but more than two pairs are seldom needed.

Dynamically order a facet's values

To configure how the facet values of a specified facet are to be ordered, follow these steps:

Export the configuration of the ATG owner’s attributes, using the following endpoint:
GET /gsadmin/v1/cloud/attributes/ATG
In the exported _.json file, copy the facet attribute that you are interested in.
Add or update this attribute’s displayConfig parameter, and specify the sort option and sort order for the facet values in that facet. For example:
"displayConfig": {"sort": "count,desc;displayName,asc"},
Upload this updated configuration definition to the following endpoint:
PUT /gsadmin/v1/cloud/attributes/system/<facet-name>
Verify your changes have taken effect by calling the following endpoint and ensuring it shows the new displayConfig property in the list of system attributes:
GET /gsadmin/v1/cloud/attributes/system
Run an index to have your changes take effect:
POST /ccadmin/v1/search/index { “op”: “partial” }

Facet values ordered by displayOrder

If the facet is ordered by displayOrder a displayConfig is specified as follows:

"displayConfig": {  "sort":
        "displayOrder,desc"
    }

Then, an additional step is required: You must provide the relative order of each value. To do so, follow these steps:

Update the Facets data store with a displayOrder for each value using the API endpoint POST /gsdata/v1/cloud/facets/<facet-name>. For example, to update a Decade facet with values of 80s, 90s, 00s, 10s, and so on in logical order, you would use the following endpoint and payload:

POST /gsdata/v1/cloud/facets/product.x_decade
{
    "items": [
 { 
     "key" : "60s",
     "displayOrder" : "6"
 }, 
 {
     "key" : "70s",
     "displayOrder" : "5"
 },
 {
     "key" : "80s",
     "displayOrder" : "4"
 },
 {
      "key" : "90s",
     "displayOrder" : "3"
 },
 {
      "key" : "00s",
     "displayOrder" : "2"
 },
 {
      "key" : "10s",
     "displayOrder" : "1"
 }
] }

Run an index either by triggering a publish event, or by calling the index endpoint, for example:
POST /ccadmin/v1/search/index { “op”: “partial” }
Once the index has completed, as the order is descending (sort: displayOrder,desc) values will be returned by the value of displayOrder sorting from high to low, for example:
```
1.	60s
2.	70s
3.	80s
4.	90s
5.	00s
6.	10s
```

Notes:

Values will only be available once an index has run, so if the facet is new and a publish has not been run, this will return an error.
If you need to retrieve the values for the facet, you can call the “dimvals” endpoint, for example:
GET /gsadmin/v1/cloud/dimvals/product.x_decade/children

As noted above, multiple sort options can be provided, therefore you can configure displayOrder as the primary sort option, and have a secondary sort defined too. With this combination, facet values will be divided into two buckets, the first containing values with a displayOrder and ordered using this property, followed by all values that do not have a displayOrder and ordered by the secondary sort (for example, alphabetically or by count).

Facet configuration example

This section describes an excerpt from an example _.json file and illustrates how a facet is configured. The facet is named camera.color.

The displayConfig parameter specifies that facet values in this facet are sorted in descending order of frequency; ties are sorted in ascending alphabetical order. For example, suppose that two facet values, “Action Sports Cameras” and “Binoculars” each have 44 records tagged to them. After being assigned the same location in the list by descending order of frequency, they are sorted in ascending alphabetical order. Thus “Action Sports Cameras” comes immediately before “Binoculars” in the list.

The configuration of the camera.color facet includes the parameter "mergeAction" : "update". This parameter must be included when the owner of the facet is system, as is currently required.

{
   "camera.color": {
     "isWildcardEnabledInRecordSearch": true,
     "displayOrder": 4,
     "displayConfig": {
       "sort": "freq,desc;alpha,asc"
     },
     "sourcePropertyNames": ["camera.Color of product"],
     "isAutogen": true,
     "isRecordSearchEnabled": true,
     "ecr:type": "facet",
     "mergeAction" : "update"
   }
}

Note: Do not modify facet parameters not discussed in this section unless you are certain that you have complete and accurate knowledge about those parameters.