Best Practices to Create Facet

This document helps to cover some basic questions when we try to add a new field via API.

REST URL: https://dev.hawksearch.net/api/v9/Field

Method: POST

Authentication: Basic (Engine API Key)

Please make sure that the field for the facet filter is already created otherwise you will receive an error like below :

2. When creating a new facet, you need to make sure that the following attributes are always sent in the request payload otherwise the request would be invalid.

    {
        "Name": "Age",
        "FacetType": "checkbox",
        "FieldType": "string",
        "MaxCount": 20,
        "MinHitCount": 1,
        "Field": "age",
        "DisplayType": "scrolling",
        "ScrollHeight": 150,
        "ScrollThreshold": 10,
        "TruncateThreshold": 0,
        "SearchThreshold": 0,
        "SortOrder": 22,
        "ExpandSelection": true,
        "IsCurrency": false,
        "IsNumeric": false,
        "IsSearch": false,
        "IsVisible": true,
        "IsCollapsible": true,
        "IsCollapsedDefault": false,
       "ShowSliderInputs": true
    }

3. Please make sure to create one facet for each field. If you try to create multiple facets using the same field name then you will get a notification like below.

4. How to utilize FacetFieldType and FacetType in association with each other?

When adding facet field type, we can only add the facet types valid for that specific field.

Facet Field Type	Facet Type
String	checkbox (Checkbox List) link (Link List) nestedcheckbox (Nested Checkbox) nestedlinklist (Nested Link List) size (Size) swatch (Swatch) rating (Rating)
Search	related (Related Searches) recentsearches (Recent Searches) search (Search Within)
Range	checkbox (Checkbox List) link (Link List) slider (Slider)
Numeric	checkbox (Checkbox List) link (Link List) nestedcheckbox (Nested Checkbox) nestedlinklist (Nested Link List) size (Size) swatch (Swatch) rating (Rating)

Valid Request:

 {
        "Name": "Age",
        "FacetType": "checkbox",
        "FieldType": "string",
        "MaxCount": 20,
        "MinHitCount": 1,
        "Field": "age",
        "DisplayType": "scrolling",
        "ScrollHeight": 150,
        "ScrollThreshold": 10,
        "TruncateThreshold": 0,
        "SearchThreshold": 0,
        "SortOrder": 22,
        "ExpandSelection": true,
        "IsCurrency": false,
        "IsNumeric": false,
        "IsSearch": false,
        "IsVisible": true,
        "IsCollapsible": true,
        "IsCollapsedDefault": false,
       "ShowSliderInputs": true
    }

Invalid Request:

FacetType ‘checkbox’ cannot be used with FieldType ‘search’.

   {
        "Name": "Age",
        "FacetType": "checkbox",
        "FieldType": "search",
        "MaxCount": 20,
        "MinHitCount": 1,
        "Field": "age",
        "DisplayType": "scrolling",
        "ScrollHeight": 150,
        "ScrollThreshold": 10,
        "TruncateThreshold": 0,
        "SearchThreshold": 0,
        "SortOrder": 22,
        "ExpandSelection": true,
        "IsCurrency": false,
        "IsNumeric": false,
        "IsSearch": false,
        "IsVisible": true,
        "IsCollapsible": true,
        "IsCollapsedDefault": false,
       "ShowSliderInputs": true
    }

5. There are 3 options available for DisplayType:

If "DisplayType": "scrolling", please set up ‘ScrollHeight’ and ‘ScrollThreshold’ attributes. By default ScrollHeight= 150 and ScrollThreshold = 10. TruncateThreshold needs to be set to 0 when DisplayType=scrolling.
If "DisplayType": "truncating", ScrollHeight and ScrollThreshold needs to be set to 0. Please set up ‘TruncateThreshold’ for this display type which is just a numeric value N indicating the first N values that should show up in the facet.
If "DisplayType": "default", ‘TruncateThreshold’, ‘ScrollHeight' and 'ScrollThreshold’ needs to be set to 0.

6. ‘Is Search Enabled?’ and ‘Search Threshold’.

‘IsSearch’ attribute makes the facet searchable for its filters. This is useful for facets containing more than 15 values in general. If IsSearch is set to true then you can specify the minimum number of filters to be present in the facet to make it searchable by using SearchThreshold attribute. SearchThreshold should have a numeric value.

7. Range facet versus Checkbox list facet for numeric fields.

The default display type option is the checkbox list for a given facet. This displays all the values available corresponding to its mapped field and the resulting items.

For a facet mapped to be numeric field, this display type is usually not ideal if the field has high number of decimal values, and they are different for every product, the checkbox facet corresponding to this will be huge with one product per facet value as below:

in the above case, users are forced to search for the exact value and the UI also isn't appealing in this case. This also adds to performance issues do to the aggregations required to pull of every facet value.

Instead, we can change the display type to a range slider facet:

This is elegant, simple and user friendly approach to display a numeric field’s facet. The user can also enter the desired value to filter by and this has better performance also.