Programming with facets
Facets are filters that allow storefront customers to narrow their search
according to catalog entry attributes. You can control the behavior of facets by changing
how attributes are displayed. For example, a product with an attribute named
size could display the four allowed values of the attribute as
S, M, L, XL
.
Basic facet flow in the Query service
When a query is submitted, the following sequence occurs to evaluate any referenced
facets.
- The attribute index in SearchByFacetExpressionProvider.java class is accessed to gather properties of the facetable attributes. This operation is performed to determine whether facets are applicable to category navigation or a keyword search. If facets are applicable to the query, the class returns a list of the properties applicable to those facets.
- Once the Query service receives the facet list, it runs a facet aggregation operation in SearchFacetQueryPreprocessor.class on the facet.* fields.
- Elasticsearch is then queried, and returns the count of each facet value. This count is merged with the properties provided by the first step, and written in the facet section of search response.
The following facet properties are available for the search response:
- value
- The index field name on which we have done aggregation to fetch this facet.
- name
- The field name to display in the storefront.
- entry
- The list of facet value with its count and name to be displayed in the
storfront. For example:
{ "label": "Bender Home Fashions", "value": "manufacturer.raw%3A%22Bender+Home+Fashions%22", "count": "1", "extendedData": { "uniqueId": "661011101001011143272111109101327097115104105111110115" } }
- extendedData
- Additional data needed by the storefront to display particular facets. For
example:
- fname
- Same as the name field.
- propertyvalue
- Same as the value field.
- maximumValuesToDisplay
- How many facet value should be displayed on storefront. If
nothing is mentioned then default value is
20
. - displayable
- Whether the Facet is displayable in the storefront.
- allValuesReturned
- If the size of values returned in entry
field is greater than
maximumValuesToDisplay then set this
property to
false
. Default istrue
. - zero_display
- If this is marked to
true
then while faceting the values whose count is zero are also returned in response. Default isfalse
. - allowMultipleValueSelection
- If facet allows multiple values to be selected or not.
- displaySequence
- Sequence number for particular facet. This field is use on storefront to display facet in asending order.
- name
- Same as name field.
- sortorder
- The display order to use when displaying the values for the facet.
- max_display
- Number of values to be displayed at once.
- fdesc
- Description of the facet.
- propertyId
- Same as 'value' field.
Search default facets
HCL Commerce Search comes with the following three default facets:
- 1. Category
- Category facet aggregation is done on
path.${catalogId}
field - 2. Brand
- Brand facet aggregation is done on manufacture.raw field.
- 3. Price
- Price facet aggregation is done on
price.${contractId}.${currency}
Facet behaviors when working with other Search related configurations
The following sections describe the behavior of facets when certain Search
configurations have been enabled or disabled. For more informiation about facets,
see the Facets topic.
- Expanded Navigation
- For an introduction to category navigation facets, see Category-based browsing by using HCL Commerce Search. Facets with expanded
navigation enabled provide the following functionality:
- Facets from all the subcategories are displayed at parent category.
- The count of the facets is same as the sum of counts for all subcategories for that particular facet.
- By default, only category facets are displayed at non-leaf categories.
- Result Grouing
- Result grouping in Elastic search based solution is similar to product
grouping explained in Product grouping, as used
in keyword search facet. Facets with result grouping behave as
follows:
- Initially when any facet is not selected the facet count that is displayed is based on the product count.
- When any facet is selected and a filter is applied, the facet count is the product count but only for those products which has at least one SKU.
- With result grouping enabled, you can decide the facet level by
using the search profile parameter
facetLevel. By default the
facetLevel is the product level. To
switch to sku level, give the parameter the value
item
. When you use SKU level facets then the count of each facet will come from the SKU. (For example for one product, if three SKU have the same facet value then the count will be three for that facet, instead of one.)
- When result grouping is disabled the facet count comes from product only. No SKU calls are made.
- Facet related wc-component properties
- the following settings from wc-components can also
be used to enhance or restrict the default facet capability:
- FacetPageSize
- Used when fetching facets from the attribute index in the
FacetHelper.java class. The maximum
number of attributes fetched at once by default is
1000
. - displayLeafCategoriesOnly
- When doing keyword search if you want to display only leaf
categories in the Category facet then set this as
true
. The default value isfalse
, which means that the Category facet displays parent categories also. - useCategoryFacetDisplaySettingsForSearch
- EnableDeepFacets
- This is used to override expanded category navigation for category navigation facets.
- StaticPriceRangeFacet
- If this is set to
true
then a hardcoreded price range from the database is used instead of creating a range based on price values. But default it is set tofalse
. - ExecuteSeparateMainResultAndFacetQuery
- MergeProductAndSKUFacet