The facet request object

Request structure and objects

You can add a facet object to a Sitecore Discover Search and Recommendation request to specify the type of facet and other facet properties you want in the response.

The following code sample shows the structure of the facet object in a request:

{
  "all": false,
  "max": 10,
  "total": false,
  "empty": false,
  "sort": {
    "type": "text",
    "order": "asc"
  },
  "brand": {
    "min_count": 1,
    "max": 10,
    "total": false,
    "sort": {
      "type": "text",
      "order": "asc"
    },
    "in_content": "<content_type>",
    "field": [
      "<field_type"
    ],
    "value": [
      <facet_type_value_or_id>
    ]
  }
}

The following table describes the keys in the facet object:

Key	Type	Description
all	Boolean	Optional.Gets all facet types.Default: false.
max	integer	Optional.The maximum number of facet values per facet_type.Use -1 to get the maximum allowed set of facet values.NoteIf you request too many facet values, you see a lag in response times. We recommend that you use -1 to allow the system to return the optimal number of facet values. If you need more than the maximum allowed facet values, contact Discover.Default: 10.
total	Boolean	Optional.If true, returns the total number of facet values for each <facet_type>.Useful when you use the max key to limit the number of values returned, but you still want to know the total number of facet values.Default: false.
empty	Boolean	Optional.If false, returns the requested facets even if a given facet has no applicable filter in the response.Default: false.
sort	sort object	Optional.Determines the sort order of the facet values.NoteThe facet sort object does not overwrite the The sort request object because they are independent.
brand	Facet type object	Optional.Returns a facet type that allows users to filter by product brands.You can have more than one facet type object.
category_names	Facet type object	Optional.Returns a facet that allows users to filter by category names.You can have more than one facet type object.
price	Facet type object	Optional.Returns a facet that allows users to filter by price or price range.You can have more than one facet type object.
rating	Facet type object	Optional.Returns a facet that allows users to filter by product review rating. You must specify a minimum and a maximum.You can have more than one facet type object.

Note

The brand, category_names, price, and rating facet types are default and come with all implementations. You can define additional facet types that are specific to your industry when you do the initial data feed.

The following table describes the keys in the facet type object:

Key	Type/default value	Description
`min_count`	integer	Optional. Minimum count of any returned facet value. Default: `1`
`max`	integer	Optional. The maximum number of facet values for this `facet_type`. This key overrides the facet `max` value for this `facet_type`. Default: `10`
`total`	Boolean	Optional. If `true`, returns the total number of facet values for this `facet_type`. This key overrides the facet `total` for this `facet_type`. Default: `false`
`in_content`	string	Optional. The `content_type` of the `facet_type`. Default: `product`
`sort`	Sort object	Optional. Determines the sort order of the facet values of this facet type. This key overrides the facet `sort` for this `facet_type`.
`field`	array of strings	Optional. Additional fields returned in the facet value. Default: empty.
`value`	array of strings	Optional. Returns fixed facet values. Default: empty.
`keyphrase`	string	Optional. Returns facet values that match the given keyphrase. Default: empty.

Sort object

The following table describes the keys in the sort object:

Key	Type	Description	Value
type	string	Required.Whether you want to sort facets alphabetically or by the number of items that have this value.For example, a search result has five red and four blue items. If you specify the sort type as count, the red items appear first because there are more red items than blue.	count (default)text
order	string	Required.Whether you want to sort facets in an ascending or descending order.	desc (default)asc

Example

The following shows an example of a facet object in a request to:

Return 2 facet values per <facet_type>.
Sort the facet values in alphabetical order.
For color, return color_id_10 and color_id_2 if the count is not equal to 0.
For category, give 15 facet values (instead of 2) and return the facet value with a count greater than or equal to 5.

{
    "facet": {
 	   "max": 2,
   	 "sort": {
   	   "value": [
   	       {"type": "text", "order": "asc"}
        	]
      	}
    	},
    	"colors": {
      	"value": ["color_id_10", "color_id_2"]
   	 },
    	"category_names": {
	    "min_count":5,
	    "max": 15
 }

If you have suggestions for improving this article, let us know!

The facet request object

Facet type object

Sort object

Example