Managing Facets

📘

API Docs

Detailed technical documentation is available here - Managing Facets API Documentation

Using API to Create Facets

This API allows you to create a facet in Hawksearch dashboard and manage the facet configurations.

Example use case: Create a Brand facet that can be used as a facet filter.

Request: POST request to the API below:

Add facet API Documentation

   
    {
        "SyncGuid": "00000000-0000-0000-0000-000000000000",
        "FacetId": 0,
        "Name": "Brand",
        "FacetType": "checkbox",
        "FieldType": "string",
        "MaxCount": 0,
        "MinHitCount": 0,
        "Field": "brand",
        "Param": null,
        "DisplayType": "default",
        "ScrollHeight": 0,
        "ScrollThreshold": 0,
        "TruncateThreshold": 0,
        "SearchThreshold": 0,
        "SortOrder": 0,
        "ExpandSelection": false,
        "IsCurrency": false,
        "IsNumeric": false,
        "IsSearch": false,
        "IsVisible": true,
        "UBound": null,
        "LBound": null,
        "Increment": "0",
        "NofVisible": 0,
        "Height": 0,
        "DisplayRuleXML": null,
        "SortBy": "ScoreAndAlphaAndAlpha",
        "ParentId": 0,
        "IsCollapsible": true,
        "IsCollapsedDefault": false,
        "SwatchData": null,
        "FacetRangeDisplayType": 0,
        "PreloadChildren": false,
        "Tooltip": null,
        "ShowSliderInputs": false,
        "ShowFacetImageCount": false,
        "FacetRanges": [],
        "Tags": null,
        "CreateDate": "02-04-2020",
        "ModifyDate": "02-04-2020",
        "BoostBury": {
            "BoostValues": [],
            "BuryValues": []
        },
        "ListName": "Brand Facet",
        "NumericPrecision": 0,
        "CurrencySymbol": null
    }

Response: The response is an array of facet objects, every facet object being a series of key-value pairs. Description of the data is as follows:

NoKeyDescriptionValue Type
NoKeyDescriptionValue Type
1FacetIdThe unique identifier of the facet (unique across the whole system)Number
2SyncGuidInternal fieldGUID
3NameThis is the name of the facet displayed to the user on the search results page. This property corresponds to the display name of the facet in the workbench.Alphanumeric string
4FacetTypeIndicates the mode in which the facet is displayed and configurable from the workbench. Possible values for this are:checkbox (Checkbox List)link (Link List)nestedcheckbox (Nested Checkbox)nestedlinklist (Nested Link List)size (Size)swatch (Swatch)rating (Rating)slider (Slider)related (Related Searches)recentsearches (Recent Searches)search (Search Within)One of the possible values - checkbox (String, Numeric, Range, Tabs)link (String, Numeric, Range, Tabs)nestedcheckbox (String, Numeric, Tabs)nestedlinklist (String, Numeric, Tabs)size (String, Numeric, Tabs)swatch (String, Numeric, Tabs)rating (String, Numeric, Tabs)slider (Numeric, Range)related (Search)recentsearches (Search)search (Search)
5FieldTypeDatatype of the fieldOne of the 3 possible values - SingleNumericStringSearch
6MaxCountThe integer value which indicates the maximum number of facet values which can be displayed inside the facet.

As of the Hermes release, setting the value of MaxCount to 0 is not acceptable by default to prevent potential performance issues.
Numeric
7MinHitCountThe integer value which indicates the minimum number of facet values the minimum count of filters the facet must possess in order to be displayed as an option.Numeric
8FieldThe name of the field for the facet.lowercase alphanumeric string with underscores allowed
9ParamThis is the parameter to be used if you need to apply filter using this facet. Example, if you need to filter by the brand "The North Face"" then in send the parameter ""brand=The North Face"" in addition to the other filters."Alphanumeric
10DisplayTypeThis is the property which provides options to fine-tune the way the list of facet values will be displayed. In the JSON output, the three different choices that will determine what fields will need to be defined in lowercase:scrollingdefaulttruncatingString
11ScrollHeightThis is used when the facet's DisplayType is set to scroll. It sets the height of the facet in pixels.Numeric
12ScrollThresholdThis is used when the facet's DisplayType is set to scroll. It sets the minimum limit for the number of filters to be present in the facet for it to be displayed in a scrolling manner.Numeric
13TruncateThresholdThis is used when the facet's DisplayType is set to Truncating.The truncated facet shows only the first N values where N is the number set in the workbench, to load more values, user needs to click the "show more"" link."Numeric
14SearchThresholdIt specifies the minimum number of filters to be present in the facet to make it search-able. The facet needs to have "Is Search Enabled?"" set to onin other words IsSearch property needs to be true."
15IsCurrencyIndicates if the facet needs to display the currency symbol. If the facet's FieldType is set as either numeric or range, and the display type is slider, then this option is displayed.Boolean
16IsNumericIndicator for range type of facets to show the slider. This property is hidden for all other facet types.Boolean
17IsSearchThis makes the facet searchable for its filters. This is useful for facets containing more than 15 values in general.Boolean
18IsVisibleBoolean switch to toggle the visibility of the facetBoolean
19UBoundIndicates the upper bound of the range facet.Numeric
20LBoundIndicates the lower bound of the range facet.Numeric
21IncrementSetting up the range facet slider valueNumeric
22NofVisibleNumber of Visible Facet valuesNumeric
23HeightHeight of the scrollable facet valuesNumeric
24DisplayRuleXMLDisplay rule details of the facet in XML formatXML
25SortByIndicates the default sort order of the facet.Numeric
26ParentIdParentId of the facet for Hierarchial facets.Numeric
27IsCollapsibleBoolean value indicating whether the facet can be completely collapsed into a headerBoolean
28IsCollapsedDefaultBoolean value indicating collapsible displayBoolean
29SwatchDataA special type of facet is a swatch which displays images instead of the facet filters. The JSON output consists of the list of images. This is most useful for colors.Alphanumeric
30FacetRangeDisplayTypeNumeric value to indicate the sub type of the facet when it is a range.Numeric
31PreloadChildrenNested facets can load children filters either upon click event of the parent filter or automatically. This choice can be opted based on the value of this property.Boolean
32TooltipQuick help for the user available when hovered over the question mark next to the facet nameAlphanumeric
33ShowSliderInputsFor slider facet, the user-entered inputs can be made visible using this property.Boolean
34ShowFacetImageCountBoolean value to show or hide facet image countBoolean
35FacetRangesIt consistes of FacetRangeModel object.FacetRangeModel Object
36TagsTags assocaited with a facetAlphanumeric
37CreateDateFacet Creation DateDate string in MM-DD-YYYY format
38ModifyDateFacet Modification DateDate string in MM-DD-YYYY format
39BoostValuesBoost value of a facetNumeric
40BuryValuesBury value of a facetNumeric
41ListNameName of the facet which is not displayed to front end users.Alphanumeric
42NumericPrecisionNumericNumeric
43CurrencySymbolIf facet type uses CurrencyAlphanumeric
44ExpandSelectionThis field controls whether or not you will allow your customer to see additional filters after making their initial selection. All relevant sub departments will still be returned, but other filters not related to the initial selection will be hidden if this option is set to NO. If the option is set to YES, then the top level filters, and each layer of additional sub-departments, will be displayed. This is helpful if you have a department that has hundreds of sub-departments, for example. You can limit the number of filters that your customers can view so as not to overwhelm them.Boolean
{
    "SyncGuid": "c050f99e-5cfd-433e-9bee-219a3d437061",
    "FacetId": 171214,
    "Name": "Brand",
    "FacetType": "checkbox",
    "FieldType": "string",
    "MaxCount": 0,
    "MinHitCount": 0,
    "Field": "brand",
    "Param": null,
    "DisplayType": "default",
    "ScrollHeight": 0,
    "ScrollThreshold": 0,
    "TruncateThreshold": 0,
    "SearchThreshold": 0,
    "SortOrder": 0,
    "ExpandSelection": false,
    "IsCurrency": false,
    "IsNumeric": false,
    "IsSearch": false,
    "IsVisible": true,
    "UBound": null,
    "LBound": null,
    "Increment": "0",
    "NofVisible": 0,
    "Height": 0,
    "DisplayRuleXML": null,
    "SortBy": "ScoreAndAlphaAndAlpha",
    "ParentId": 0,
    "IsCollapsible": true,
    "IsCollapsedDefault": false,
    "SwatchData": null,
    "FacetRangeDisplayType": 0,
    "PreloadChildren": false,
    "Tooltip": null,
    "ShowSliderInputs": false,
    "ShowFacetImageCount": false,
    "FacetRanges": [],
    "Tags": null,
    "CreateDate": "02-04-2020",
    "ModifyDate": "02-04-2020",
    "BoostBury": {
        "BoostValues": [],
        "BuryValues": []
    },
    "ListName": "Brand Facet",
    "NumericPrecision": 0,
    "CurrencySymbol": null
}

Special facets considerations:

Swatch facets : facets defined as swatch need to have their swatches defined in the below json format:

"SwatchData": "[{\"Value\":\"White\",\"AssetName\":\"white2.png\",\"AssetUrl\":\"\",\"IsDefault\":true,\"Color\":null},
{\"Value\":\"empty\",\"AssetName\":\"emptySwatch.png\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},
{\"Value\":\"red\",\"AssetName\":\"reg.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},
{\"Value\":\"green\",\"AssetName\":\"green.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},
{\"Value\":\"brown\",\"AssetName\":\"brown.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},
{\"Value\":\"black\",\"AssetName\":\"black.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},
{\"Value\":\"Blue\",\"AssetName\":\"blue.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},
{\"Value\":\"Navy\",\"AssetName\":\"navy.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},
{\"Value\":\"Yellow\",\"AssetName\":\"yellow.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},
{\"Value\":\"Purple\",\"AssetName\":\"purple.png\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null},
{\"Value\":\"Grey\",\"AssetName\":\"grey.jpg\",\"AssetUrl\":null,\"IsDefault\":false,\"Color\":null}]"

Display Rule: this is defined by XML as below, it is advised to create a facet with a display rule on the dashboard to better understand the format:

"DisplayRuleXML": "<?xml version=\"1.0\" encoding=\"utf-16\"?>\r\n
<Rule xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" Operator=\"Any\" RuleType=\"Group\">\r\n  
<Rules>\r\n    <Rule Operator=\"None\" RuleType=\"Eval\">\r\n     
 <Field>landingpage:landingpage</Field>\r\n      
 <Condition>is</Condition>\r\n      
 <Value>4147787</Value>\r\n    
 </Rule>\r\n  
 </Rules>\r\n  
 <Field />\r\n  
 <Condition />\r\n  
 <Value />\r\n
 </Rule>"

Boost and Bury: these are defined as arrays of objects with these properties

    ...
    "BoostBury": {
        "BoostValues": [
            {
                "Value": "Patagonia",
                "SortOrder": 0
            },
            {
                "Value": "The North Face",
                "SortOrder": 1
            },
            {
                "Value": "Columbia Sportswear",
                "SortOrder": 2
            },
            {
                "Value": "Adventure Medical Kits",
                "SortOrder": 3
            }
        ],
        "BuryValues": [
            {
                "Value": "Jet Boil",
                "SortOrder": 1
            }
        ]
    },
    ...

Facet Ranges: Facets defined as ranges can have minimum and maximum values defined by the LBound and UBound attributes under FacetRanges object

 ...
 "FacetRanges": [
        {
            "RangeId": 69300,
            "Name": "Label 1",
            "LBound": "1",
            "UBound": "10",
            "SortOrder": 1,
            "AssetName": "",
            "AssetUrl": ""
        },
        {
            "RangeId": 69301,
            "Name": "Label 2",
            "LBound": "11",
            "UBound": "20",
            "SortOrder": 2,
            "AssetName": "",
            "AssetUrl": ""
        }
    ],
    ...

Best Practices to Create Facet

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

Add facet API Documentation

Method: POST

Authentication: Basic (Engine API Key)

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

  1. 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
    }
  1. 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.

  1. 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 TypeFacet Type
Stringcheckbox (Checkbox List)link (Link List)nestedcheckbox (Nested Checkbox)nestedlinklist (Nested Link List)size (Size)swatch (Swatch)rating (Rating)
Searchrelated (Related Searches)recentsearches (Recent Searches)search (Search Within)
Rangecheckbox (Checkbox List)link (Link List)slider (Slider)
Numericcheckbox (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
    }
  1. There are 3 options available for DisplayType:
    1. 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.
    2. 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.
    3. If "DisplayType": "default", ‘TruncateThreshold’, ‘ScrollHeight' and 'ScrollThreshold’ needs to be set to 0.
  2. ‘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.

  1. 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.

Using API to Update Facets

This API allows you to update a facet in Hawksearch dashboard and manage the facet configurations.

Example use case: Update a Brand facet name.

Request: PUT request to the API below:

Get facet by id API Documentation

    {
        "SyncGuid": "c050f99e-5cfd-433e-9bee-219a3d437061",
        "FacetId": 171214,
        "Name": "Brand Update Name",
        "FacetType": "checkbox",
        "FieldType": "string",
        "MaxCount": 0,
        "MinHitCount": 0,
        "Field": "brand",
        "Param": null,
        "DisplayType": "default",
        "ScrollHeight": 0,
        "ScrollThreshold": 0,
        "TruncateThreshold": 0,
        "SearchThreshold": 0,
        "SortOrder": 5,
        "ExpandSelection": false,
        "IsCurrency": false,
        "IsNumeric": false,
        "IsSearch": false,
        "IsVisible": true,
        "UBound": null,
        "LBound": null,
        "Increment": "0",
        "NofVisible": 0,
        "Height": 0,
        "DisplayRuleXML": null,
        "SortBy": "ScoreAndAlphaAndAlpha",
        "ParentId": 0,
        "IsCollapsible": true,
        "IsCollapsedDefault": false,
        "SwatchData": null,
        "FacetRangeDisplayType": 0,
        "PreloadChildren": false,
        "Tooltip": null,
        "ShowSliderInputs": false,
        "ShowFacetImageCount": false,
        "FacetRanges": [],
        "Tags": null,
        "CreateDate": "03-08-2021",
        "ModifyDate": "03-08-2021",
        "BoostBury": {
            "BoostValues": [],
            "BuryValues": []
        },
        "ListName": "Brand Facet",
        "NumericPrecision": 0,
        "CurrencySymbol": null
    }

Response: The response is an array of facet objects, every facet object being a series of key-value pairs. Description of the data is as follows:

NoKeyDescriptionValue Type
1FacetIdThe unique identifier of the facet (unique across the whole system)Number
2SyncGuidInternal fieldGUID
3NameThis is the name of the facet displayed to the user on the search results page. This property corresponds to the display name of the facet in the workbench.Alphanumeric string
4FacetTypeIndicates the mode in which the facet is displayed and configurable from the workbench. Possible values for this are:checkbox (Checkbox List)link (Link List)nestedcheckbox (Nested Checkbox)nestedlinklist (Nested Link List)size (Size)swatch (Swatch)rating (Rating)slider (Slider)related (Related Searches)recentsearches (Recent Searches)search (Search Within)One of the possible values - checkbox (String, Numeric, Range, Tabs)link (String, Numeric, Range, Tabs)nestedcheckbox (String, Numeric, Tabs)nestedlinklist (String, Numeric, Tabs)size (String, Numeric, Tabs)swatch (String, Numeric, Tabs)rating (String, Numeric, Tabs)slider (Numeric, Range)related (Search)recentsearches (Search)search (Search)
5FieldTypeDatatype of the fieldOne of the 3 possible values - SingleNumericStringSearch
6MaxCountThe integer value which indicates the maximum number of facet values which can be displayed inside the facet.Numeric
7MinHitCountThe integer value which indicates the minimum number of facet values the minimum count of filters the facet must possess in order to be displayed as an option.Numeric
8FieldThe name of the field for the facet.lowercase alphanumeric string with underscores allowed
9ParamThis is the parameter to be used if you need to apply filter using this facet. Example, if you need to filter by the brand "The North Face"" then in send the parameter ""brand=The North Face"" in addition to the other filters."Alphanumeric
10DisplayTypeThis is the property which provides options to fine-tune the way the list of facet values will be displayed. In the JSON output, the three different choices that will determine what fields will need to be defined in lowercase:scrollingdefaulttruncatingString
11ScrollHeightThis is used when the facet's DisplayType is set to scroll. It sets the height of the facet in pixels.Numeric
12ScrollThresholdThis is used when the facet's DisplayType is set to scroll. It sets the minimum limit for the number of filters to be present in the facet for it to be displayed in a scrolling manner.Numeric
13TruncateThresholdThis is used when the facet's DisplayType is set to Truncating.The truncated facet shows only the first N values where N is the number set in the workbench, to load more values, user needs to click the "show more"" link."Numeric
14SearchThresholdIt specifies the minimum number of filters to be present in the facet to make it search-able. The facet needs to have "Is Search Enabled?"" set to onin other words IsSearch property needs to be true."Numeric
15IsCurrencyIndicates if the facet needs to display the currency symbol. If the facet's FieldType is set as either numeric or range, and the display type is slider, then this option is displayed.Boolean
16IsNumericIndicator for range type of facets to show the slider. This property is hidden for all other facet types.Boolean
17IsSearchThis makes the facet searchable for its filters. This is useful for facets containing more than 15 values in general.Boolean
18IsVisibleBoolean switch to toggle the visibility of the facetBoolean
19UBoundIndicates the upper bound of the range facet.Numeric
20LBoundIndicates the lower bound of the range facet.Numeric
21IncrementSetting up the range facet slider valueNumeric
22NofVisibleNumber of Visible Facet valuesNumeric
23HeightHeight of the scrollable facet valuesNumeric
24DisplayRuleXMLDisplay rule details of the facet in XML formatXML
25SortByIndicates the default sort order of the facet.Numeric
26ParentIdParentId of the facet for Hierarchial facets.Numeric
27IsCollapsibleBoolean value indicating whether the facet can be completely collapsed into a headerBoolean
28IsCollapsedDefaultBoolean value indicating collapsible displayBoolean
29SwatchDataA special type of facet is a swatch which displays images instead of the facet filters. The JSON output consists of the list of images. This is most useful for colors.Alphanumeric
30FacetRangeDisplayTypeNumeric value to indicate the sub type of the facet when it is a range.Numeric
31PreloadChildrenNested facets can load children filters either upon click event of the parent filter or automatically. This choice can be opted based on the value of this property.Boolean
32TooltipQuick help for the user available when hovered over the question mark next to the facet nameAlphanumeric
33ShowSliderInputsFor slider facet, the user-entered inputs can be made visible using this property.Boolean
34ShowFacetImageCountBoolean value to show or hide facet image countBoolean
35FacetRangesIt consistes of FacetRangeModel object.FacetRangeModel Object
36TagsTags assocaited with a facetAlphanumeric
37CreateDateFacet Creation DateDate string in MM-DD-YYYY format
38ModifyDateFacet Modification DateDate string in MM-DD-YYYY format
39BoostValuesBoost value of a facetNumeric
40BuryValuesBury value of a facetNumeric
41ListNameName of the facet which is not displayed to front end users.Alphanumeric
42NumericPrecisionNumericNumeric
43CurrencySymbolIf facet type uses CurrencyAlphanumeric
44ExpandSelectionThis field controls whether or not you will allow your customer to see additional filters after making their initial selection. All relevant sub departments will still be returned, but other filters not related to the initial selection will be hidden if this option is set to NO. If the option is set to YES, then the top level filters, and each layer of additional sub-departments, will be displayed. This is helpful if you have a department that has hundreds of sub-departments, for example. You can limit the number of filters that your customers can view so as not to overwhelm them.Boolean
{
    "SyncGuid": "c050f99e-5cfd-433e-9bee-219a3d437061",
    "FacetId": 171214,
    "Name": "Brand Update Name",
    "FacetType": "checkbox",
    "FieldType": "string",
    "MaxCount": 0,
    "MinHitCount": 0,
    "Field": "brand",
    "Param": null,
    "DisplayType": "default",
    "ScrollHeight": 0,
    "ScrollThreshold": 0,
    "TruncateThreshold": 0,
    "SearchThreshold": 0,
    "SortOrder": 5,
    "ExpandSelection": false,
    "IsCurrency": false,
    "IsNumeric": false,
    "IsSearch": false,
    "IsVisible": true,
    "UBound": null,
    "LBound": null,
    "Increment": "0",
    "NofVisible": 0,
    "Height": 0,
    "DisplayRuleXML": null,
    "SortBy": "ScoreAndAlphaAndAlpha",
    "ParentId": 0,
    "IsCollapsible": true,
    "IsCollapsedDefault": false,
    "SwatchData": null,
    "FacetRangeDisplayType": 0,
    "PreloadChildren": false,
    "Tooltip": null,
    "ShowSliderInputs": false,
    "ShowFacetImageCount": false,
    "FacetRanges": [],
    "Tags": null,
    "CreateDate": "03-08-2021",
    "ModifyDate": "03-08-2021",
    "BoostBury": {
        "BoostValues": [],
        "BuryValues": []
    },
    "ListName": "Brand Facet",
    "NumericPrecision": 0,
    "CurrencySymbol": null
}

Update facet to add a display rule

This API allows you to update a facet in Hawksearch dashboard and manage the facet configurations.

Update facet by id API Documentation

Example use case: Add a display rule for the Price facet so that it is only visible when Brand is ‘Columbia Sportswear’.

📘

Note:

Please pass the FacetId in the PUT request below.

Request: PUT request to the API:

   {
        "SyncGuid": "e96a399a-f25b-4311-bf26-68c958f5bfl8",
        "FacetId": 83284,
        "Name": "Price",
        "FacetType": "checkbox",
        "FieldType": "numeric",
        "MaxCount": 30,
        "MinHitCount": 1,
        "Field": "price",
        "Param": "",
        "DisplayType": "default",
        "ScrollHeight": 0,
        "ScrollThreshold": 0,
        "TruncateThreshold": 0,
        "SearchThreshold": 0,
        "SortOrder": 20932,
        "ExpandSelection": false,
        "IsCurrency": true,
        "IsNumeric": true,
        "IsSearch": false,
        "IsVisible": true,
        "UBound": null,
        "LBound": null,
        "Increment": "0",
        "NofVisible": 10,
        "Height": 0,
        "DisplayRuleXML": "<?xml version=\"1.0\" encoding=\"utf-16\"?>\r\n<Rule xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" Operator=\"Any\" RuleType=\"Group\">\r\n  <Rules>\r\n    <Rule Operator=\"None\" RuleType=\"Eval\">\r\n      <Rules />\r\n      <Field>facet:brand</Field>\r\n      <Condition>is</Condition>\r\n      <Value>Columbia Sportswear</Value>\r\n    </Rule>\r\n  </Rules>\r\n  <Field />\r\n  <Condition />\r\n  <Value />\r\n</Rule>",
        "SortBy": "Ascending",
        "ParentId": 0,
        "IsCollapsible": true,
        "IsCollapsedDefault": false,
        "SwatchData": null,
        "FacetRangeDisplayType": 0,
        "PreloadChildren": false,
        "Tooltip": "Price",
        "ShowSliderInputs": true,
        "ShowFacetImageCount": true,
        "FacetRanges": [
            {
                "RangeId": 72624,
                "Name": "$0 - $150.99\t",
                "LBound": "0",
                "UBound": "150.99",
                "SortOrder": 1,
                "AssetName": "",
                "AssetUrl": ""
            },
            {
                "RangeId": 72625,
                "Name": "$151 - $200.99",
                "LBound": "151",
                "UBound": "200.99",
                "SortOrder": 2,
                "AssetName": "",
                "AssetUrl": ""
            },
            {
                "RangeId": 72626,
                "Name": "$201 - $500",
                "LBound": "201",
                "UBound": "500",
                "SortOrder": 3,
                "AssetName": "",
                "AssetUrl": ""
            },
            {
                "RangeId": 72627,
                "Name": "$501 - $750",
                "LBound": "501",
                "UBound": "750",
                "SortOrder": 4,
                "AssetName": "",
                "AssetUrl": ""
            },
            {
                "RangeId": 72628,
                "Name": "$751 - $1000",
                "LBound": "751",
                "UBound": "1000",
                "SortOrder": 5,
                "AssetName": "",
                "AssetUrl": ""
            },
            {
                "RangeId": 72629,
                "Name": "$1000 - $2000",
                "LBound": "1000",
                "UBound": "2000",
                "SortOrder": 6,
                "AssetName": "",
                "AssetUrl": ""
            },
            {
                "RangeId": 72630,
                "Name": "$2000 - $3000",
                "LBound": "2000",
                "UBound": "3000",
                "SortOrder": 7,
                "AssetName": "",
                "AssetUrl": ""
            },
            {
                "RangeId": 72631,
                "Name": "$3000 and Up",
                "LBound": "3000",
                "UBound": "999999999",
                "SortOrder": 8,
                "AssetName": "",
                "AssetUrl": ""
            }
        ],
        "Tags": "",
        "CreateDate": "01-01-0001",
        "ModifyDate": "04-12-2021",
        "BoostBury": {
            "BoostValues": [],
            "BuryValues": []
        },
        "ListName": "Price",
        "NumericPrecision": 0,
        "CurrencySymbol": null
    }

Response: The response is an array of facet objects, every facet object being a series of key-value pairs. Description of the data is as follows:

NoKeyDescriptionValue Type
1FacetIdThe unique identifier of the facet (unique across the whole system)Number
2SyncGuidInternal fieldGUID
3NameThis is the name of the facet displayed to the user on the search results page. This property corresponds to the display name of the facet in the workbench.Alphanumeric string
4FacetTypeIndicates the mode in which the facet is displayed and configurable from the workbench. Possible values for this are:checkbox (Checkbox List)link (Link List)nestedcheckbox (Nested Checkbox)nestedlinklist (Nested Link List)size (Size)swatch (Swatch)rating (Rating)slider (Slider)related (Related Searches)recentsearches (Recent Searches)search (Search Within)One of the possible values - checkbox (String, Numeric, Range, Tabs)link (String, Numeric, Range, Tabs)nestedcheckbox (String, Numeric, Tabs)nestedlinklist (String, Numeric, Tabs)size (String, Numeric, Tabs)swatch (String, Numeric, Tabs)rating (String, Numeric, Tabs)slider (Numeric, Range)related (Search)recentsearches (Search)search (Search)
5FieldTypeDatatype of the fieldOne of the 3 possible values - SingleNumericStringSearch
6MaxCountThe integer value which indicates the maximum number of facet values which can be displayed inside the facet.Numeric
7MinHitCountThe integer value which indicates the minimum number of facet values the minimum count of filters the facet must possess in order to be displayed as an option.Numeric
8FieldThe name of the field for the facet.lowercase alphanumeric string with underscores allowed
9ParamThis is the parameter to be used if you need to apply filter using this facet. Example, if you need to filter by the brand "The North Face"" then in send the parameter ""brand=The North Face"" in addition to the other filters."Alphanumeric
10DisplayTypeThis is the property which provides options to fine-tune the way the list of facet values will be displayed. In the JSON output, the three different choices that will determine what fields will need to be defined in lowercase:scrollingdefaulttruncatingString
11ScrollHeightThis is used when the facet's DisplayType is set to scroll. It sets the height of the facet in pixels.Numeric
12ScrollThresholdThis is used when the facet's DisplayType is set to scroll. It sets the minimum limit for the number of filters to be present in the facet for it to be displayed in a scrolling manner.Numeric
13TruncateThresholdThis is used when the facet's DisplayType is set to Truncating.The truncated facet shows only the first N values where N is the number set in the workbench, to load more values, user needs to click the "show more"" link."Numeric
14SearchThresholdIt specifies the minimum number of filters to be present in the facet to make it search-able. The facet needs to have "Is Search Enabled?"" set to onin other words IsSearch property needs to be true."Numeric
15IsCurrencyIndicates if the facet needs to display the currency symbol. If the facet's FieldType is set as either numeric or range, and the display type is slider, then this option is displayed.Boolean
16IsNumericIndicator for range type of facets to show the slider. This property is hidden for all other facet types.Boolean
17IsSearchThis makes the facet searchable for its filters. This is useful for facets containing more than 15 values in general.Boolean
18IsVisibleBoolean switch to toggle the visibility of the facetBoolean
19UBoundIndicates the upper bound of the range facet.Numeric
20LBoundIndicates the lower bound of the range facet.Numeric
21IncrementSetting up the range facet slider valueNumeric
22NofVisibleNumber of Visible Facet valuesNumeric
23HeightHeight of the scrollable facet valuesNumeric
24DisplayRuleXMLDisplay rule details of the facet in XML formatXML
25SortByIndicates the default sort order of the facet.Numeric
26ParentIdParentId of the facet for Hierarchial facets.Numeric
27IsCollapsibleBoolean value indicating whether the facet can be completely collapsed into a headerBoolean
28IsCollapsedDefaultBoolean value indicating collapsible displayBoolean
29SwatchDataA special type of facet is a swatch which displays images instead of the facet filters. The JSON output consists of the list of images. This is most useful for colors.Alphanumeric
30FacetRangeDisplayTypeNumeric value to indicate the sub type of the facet when it is a range.Numeric
31PreloadChildrenNested facets can load children filters either upon click event of the parent filter or automatically. This choice can be opted based on the value of this property.Boolean
32TooltipQuick help for the user available when hovered over the question mark next to the facet nameAlphanumeric
33ShowSliderInputsFor slider facet, the user-entered inputs can be made visible using this property.Boolean
34ShowFacetImageCountBoolean value to show or hide facet image countBoolean
35FacetRangesIt consistes of FacetRangeModel object.FacetRangeModel Object
36TagsTags assocaited with a facetAlphanumeric
37CreateDateFacet Creation DateDate string in MM-DD-YYYY format
38ModifyDateFacet Modification DateDate string in MM-DD-YYYY format
39BoostValuesBoost value of a facetNumeric
40BuryValuesBury value of a facetNumeric
41ListNameName of the facet which is not displayed to front end users.Alphanumeric
42NumericPrecisionNumericNumeric
43CurrencySymbolIf facet type uses CurrencyAlphanumeric
44ExpandSelectionThis field controls whether or not you will allow your customer to see additional filters after making their initial selection. All relevant sub departments will still be returned, but other filters not related to the initial selection will be hidden if this option is set to NO. If the option is set to YES, then the top level filters, and each layer of additional sub-departments, will be displayed. This is helpful if you have a department that has hundreds of sub-departments, for example. You can limit the number of filters that your customers can view so as not to overwhelm them.Boolean
{
    "SyncGuid": "e96a399a-f25b-4311-bf26-68c958f5bfb8",
    "FacetId": 83284,
    "Name": "Price",
    "FacetType": "checkbox",
    "FieldType": "numeric",
    "MaxCount": 30,
    "MinHitCount": 1,
    "Field": "price",
    "Param": "",
    "DisplayType": "default",
    "ScrollHeight": 0,
    "ScrollThreshold": 0,
    "TruncateThreshold": 0,
    "SearchThreshold": 0,
    "SortOrder": 20932,
    "ExpandSelection": false,
    "IsCurrency": true,
    "IsNumeric": true,
    "IsSearch": false,
    "IsVisible": true,
    "UBound": null,
    "LBound": null,
    "Increment": "0",
    "NofVisible": 10,
    "Height": 0,
    "DisplayRuleXML": "<?xml version=\"1.0\" encoding=\"utf-16\"?>\r\n<Rule xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" Operator=\"Any\" RuleType=\"Group\">\r\n  <Rules>\r\n    <Rule Operator=\"None\" RuleType=\"Eval\">\r\n     <Field>facet:brand</Field>\r\n      <Condition>is</Condition>\r\n      <Value>Columbia Sportswear</Value>\r\n    </Rule>\r\n  </Rules>\r\n</Rule>",
    "SortBy": "Ascending",
    "ParentId": 0,
    "IsCollapsible": true,
    "IsCollapsedDefault": false,
    "SwatchData": null,
    "FacetRangeDisplayType": 0,
    "PreloadChildren": false,
    "Tooltip": "Price",
    "ShowSliderInputs": true,
    "ShowFacetImageCount": true,
    "FacetRanges": [
        {
            "RangeId": 1,
            "Name": "$0 - $150.99\t",
            "LBound": "0",
            "UBound": "150.99",
            "SortOrder": 1,
            "AssetName": "",
            "AssetUrl": ""
        },
        {
            "RangeId": 2,
            "Name": "$151 - $200.99",
            "LBound": "151",
            "UBound": "200.99",
            "SortOrder": 2,
            "AssetName": "",
            "AssetUrl": ""
        },
        {
            "RangeId": 3,
            "Name": "$201 - $500",
            "LBound": "201",
            "UBound": "500",
            "SortOrder": 3,
            "AssetName": "",
            "AssetUrl": ""
        },
        {
            "RangeId": 4,
            "Name": "$501 - $750",
            "LBound": "501",
            "UBound": "750",
            "SortOrder": 4,
            "AssetName": "",
            "AssetUrl": ""
        },
        {
            "RangeId": 5,
            "Name": "$751 - $1000",
            "LBound": "751",
            "UBound": "1000",
            "SortOrder": 5,
            "AssetName": "",
            "AssetUrl": ""
        },
        {
            "RangeId": 6,
            "Name": "$1000 - $2000",
            "LBound": "1000",
            "UBound": "2000",
            "SortOrder": 6,
            "AssetName": "",
            "AssetUrl": ""
        },
        {
            "RangeId": 7,
            "Name": "$2000 - $3000",
            "LBound": "2000",
            "UBound": "3000",
            "SortOrder": 7,
            "AssetName": "",
            "AssetUrl": ""
        },
        {
            "RangeId": 8,
            "Name": "$3000 and Up",
            "LBound": "3000",
            "UBound": "999999999",
            "SortOrder": 8,
            "AssetName": "",
            "AssetUrl": ""
        }
    ],
    "Tags": "",
    "CreateDate": "01-01-0001",
    "ModifyDate": "04-12-2021",
    "BoostBury": {
        "BoostValues": [],
        "BuryValues": []
    },
    "ListName": "Price",
    "NumericPrecision": 0,
    "CurrencySymbol": null
}

DisplayRuleXML Representation Example

If the condition set for the rules for selecting products is not linear and requires multiple clauses which cannot be accommodated by the attribute_name or the attribute_value structure, please specify the entire xml for the rule as shown below.

<?xml version="1.0" encoding="UTF-8"?>
<Rule xmlns:xsd="https://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" RuleType="Group" Operator="All">
   <Rules>
      <Rule RuleType="Eval" Operator="None">
         <Field>facet:brand</Field>
         <Condition>is</Condition>
         <Value>Columbia Sportswear</Value>
      </Rule>
      <Rule RuleType="Eval" Operator="None">
         <Field>facet:subdepartment</Field>
         <Condition>is</Condition>
         <Value>Socks</Value>
      </Rule>
      <Rule RuleType="Eval" Operator="None">
         <Field>keyword:Keyword</Field>
         <Condition>contains</Condition>
         <Value>sock</Value>
      </Rule>
   </Rules>
</Rule>

Rules node

Attributes:

  • RuleType attribute specifies if the rule must be processed for a result or treated as a group with rules nested inside it. If the rules node contains further rules, then the type must be set to “Group” for that rules node. For rules that need to be evaluated, please set this attribute to “Eval.”
  • Operator specifies what the condition is for evaluation for rules with in a group. If all rules in the group need to be met to satisfy the group the value must be set to “All”. If at least one rule needs to be satisfied, please set the value to “Any”. For nested rules (not the parent rules node), if there is only one rule inside the group please set value to “None”.

Child Nodes:

  • Field: Specify the field name you want to use as part of condition
  • Condition: Specify the condition (is equal to, contains) so on
  • Value: This is the value to compare against

Using API to Delete a Facet

This API allows you to delete a facet from the Hawksearch dashboard Facet section.

Example use case: Delete Brand facet.

Delete facet by id API Documentation

Response: The response is an array of field objects, every field object being a series of key-value pairs. Description of the data is as follows:

NoKeyDescriptionValue Type
1FieldIdThe unique identifier of the field (unique across the whole system)Number
2SyncGuidInternal fieldGUID
3NameName unique to an engine (can be the same for one or more engines)lowercase alphanumeric string with underscores allowed
4FieldTypeOne of the below field configuration options:Field Values are NOT stemmedField values are ONLY stemmed (search only)Field Values indexed “as is” AND are stemmedStored only, not used for search or facetsOne of the 4 possible values - facetkeywordunindexedtext
5LabelDisplay name of the fieldAlphanumeric string
6TypeDatatype of the fieldOne of the 3 possible values - SingleNumericString
7BoostBoost value set on the fieldNumber between 1 and 200, inclusive
8FacetHandlerInternal handler associated with the fieldAlphanumeric
9IsPrimaryKeyFlag to set as primary fieldBoolean
10IsOutputFlag to control presence in responseBoolean
11IsShingleCorresponds to Add phrases to "Did you Mean"? under the field settings on the dashboardBoolean
12IsBestFragmentFlag controls creating synopses for large textual contentBoolean
13IsDictionaryFlag to include field for autocorrect suggestionsBoolean
14IsSortFlag to allow sorting on search results pageBoolean
15IsPrefixFlag to indicate if the field is a prefix typeBoolean
16IsHiddenFlag to control query builder configuration for the fieldBoolean
17IsCompareFlag to manage comparison displayBoolean
18SortOrderSort order of the fieldNumeric
19PartialQueryQuery type for the fieldNone, Prefix or Wildcard
20IsKeywordTextIndicates that the field values indexed ""as is"" AND are stemmedBoolean
21IsQueryFlag to allow querying on the fieldBoolean
22IsQueryTextFlag to show query text valueBoolean
23SkipCustomFlag to control display in custom groupBoolean
24StripHtmlFlag to remove html contentBoolean
25MinNGramAnalyzerMinimum value for ngram analyzer (for queryable fields)Numeric, 2 to 15 inclusive
26MaxNGramAnalyzerMaximum value for ngram analyzer (for queryable fields)Numeric, 2 to 15 inclusive
27CoordinateTypeUsed for latitude and logitudeAlphanumeric
28OmitNormsFlag to enable/disable smaller document to score higherBoolean
29ItemMappingField mapping valueFieldname
30DefaultValueValue to show when emptyAlphanumeric
31UseForPredictionFlag to indicate
32CopyToList of fields to copy values into (redundancy)List of alphanumeric fieldnames
33AnalyzerCorresponds to the drop down list of Analyzers to be chosenAlphanumeric
34DoNotStoreFlag to control storage (helps to increase performance by reducing index size)Boolean
35TagsEngine-wide labels (avilable acros complete dashboard)Comma separated alphanumeric string
36IterationsQuery iterationsArray of numeric values
37AnalyzerLanguageNatural language choice for query analyzerAlphanumeric
38PreviewMappingAvailable for API indexing enabled enginesFieldname
39OmitTfAndPosFlag to omit term frequencyBoolean
40CreateDateField creation dateDate string in MM-DD-YYYY format
41ModifyDateField modification dateDate string in MM-DD-YYYY format
{
    "SyncGuid": "c050f99e-5cfd-433e-9bee-219a3d437061",
    "FacetId": 171214,
    "Name": "Brand",
    "FacetType": "checkbox",
    "FieldType": "string",
    "MaxCount": 0,
    "MinHitCount": 0,
    "Field": "brand",
    "Param": null,
    "DisplayType": "default",
    "ScrollHeight": 0,
    "ScrollThreshold": 0,
    "TruncateThreshold": 0,
    "SearchThreshold": 0,
    "SortOrder": 5,
    "ExpandSelection": false,
    "IsCurrency": false,
    "IsNumeric": false,
    "IsSearch": false,
    "IsVisible": true,
    "UBound": null,
    "LBound": null,
    "Increment": "0",
    "NofVisible": 0,
    "Height": 0,
    "DisplayRuleXML": null,
    "SortBy": "ScoreAndAlphaAndAlpha",
    "ParentId": 0,
    "IsCollapsible": true,
    "IsCollapsedDefault": false,
    "SwatchData": null,
    "FacetRangeDisplayType": 0,
    "PreloadChildren": false,
    "Tooltip": null,
    "ShowSliderInputs": false,
    "ShowFacetImageCount": false,
    "FacetRanges": [],
    "Tags": null,
    "CreateDate": "03-08-2021",
    "ModifyDate": "03-08-2021",
    "BoostBury": {
        "BoostValues": [],
        "BuryValues": []
    },
    "ListName": "Brand Facet",
    "NumericPrecision": 0,
    "CurrencySymbol": null
}