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
oralpha
(alphabetical) – Sorts facet values in alphabetical order using the facet value display name. This is the default order for the Category facetcount
orfreq
- 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
orrank
– 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 endpointPOST /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 ofdisplayOrder
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.