Using faceted search
Facets are product attributes you can use as options to filter your search. Different search queries dynamically return facets. Facets are returned based on the nature of the <facet_type> and can have the following formats:
-
Term - string values
-
Range - numerical values with a minimum and a maximum
-
Nested - string values in a hierarchical structure
The following sections show examples of basic use cases for faceted search. See the facet request object to view the request data structure or see advanced use cases for more examples.
In addition to the examples here, you can also filter facets.
Getting facet values from each facet type
The following code shows a request for facet values for each <facet_type>. In this example, you want for three facet values from each facet_type.
For simplicity, assume that there are only four types: color, product_type, primary_stone_type, and primary_metal_type. In general, there are likely more than four facet types.
{
"facet": {
"all": true,
"max": 3
}
}Set the all flag to true if you want to retrieve all facet types. If you want all facet values, you can specify the max to be -1.
The following code shows the corresponding response:
{
"ts": 1480977544,
"rid": "response_id_f1",
"facet": {
"colors": {
"value": [
{"id": "color_id_red", "text": "Red", "count": 23},
{"id": "color_id_blue", "text": "Blue", "count": 11},
{"id": "color_id_yellow", "text": "Yellow", "count": 10}
]
},
"product_type": {
"value": [
{"id": "prod_type_id_ring", "text": "Ring", "count": 105},
{"id": "prod_type_id_necklace", "text": "Necklace", "count": 45},
{"id": "prod_type_id_watch", "text": "Watch", "count": 5}
]
},
"primary_stone_type": {
"value": [
{"id": "stone_id_diamond", "text": "Diamond", "count": 180},
{"id": "stone_id_ruby", "text": "Ruby", "count": 55},
{"id": "stone_id_pearl", "text": "Pearl", "count": 2}
]
},
"primary_metal_type": {
"value": [
{"id": "stone_id_gold", "text": "Gold", "count": 80},
{"id": "stone_id_silver", "text": "Silver", "count": 45},
{"id": "stone_id_white_gold", "text": "White Gold", "count": 20}
]
}
},
"facet_names": ["colors", "product_type", "primary_stone_type", "primary_metal_type"]
}Facet values are returned in descending order of the count value because this is the default facet.sort order. If you require a different sort order, see Sorting facets.
Getting many facet values for a facet
The following code shows a request to get many facet values for the same facet. In this example, you request 100 facet values for the colors facet.
{
"facet": {
"colors": {"max": 100}
}
}The following code shows the corresponding response:
{
"ts": 1480977544,
"rid": "response_id_f1",
"facet": {
"colors": {
"value": [
{"id": "color_id_red", "text": "Red", "count": 23},
{"id": "color_id_blue", "text": "Blue", "count": 11},
{"id": "color_id_yellow", "text": "Yellow", "count": 10},
{"id": "color_id_green", "text": "Green", "count": 5},
{"id": "color_id_orange", "text": "Orange", "count": 18},
{"id": "color_id_purple", "text": "Purple", "count": 2},
{"id": "color_id_white", "text": "White", "count": 3},
{"id": "color_id_grey", "text": "Grey", "count": 9},
{"id": "color_id_black", "text": "Black", "count": 11},
{"id": "color_id_multi", "text": "Multi-color", "count": 5},
{"id": "color_id_no_color", "text": "No color", "count": 17},
...
]
}
},
"facet_names": ["colors"]
}Getting a range facet
The following code shows a request to get a range facet. In this example, you request for the price range facet with three buckets.
{
"facet": {
"price": {"max": 3}
}
}The following code shows the corresponding response:
{
"ts": 1480977544,
"rid": "response_id_f2",
"facet": {
"price": {
"min": 10,
"max": 1500,
"value": [
{"id": "pR1151f20", "min": 10, "max": 200,
"text": "10 - 200", "count": 124},
{"id": "pR115Qdq", "min": 200, "max": 800,
"text": "200 - 800", "count": 89},
{"id": "pR115gGp", "min": 800, "max": 1500,
"text": "800 - 1500", "count": 94}
]
}
},
"facet_names": ["price"]
}Getting a nested facet
The following code shows a request to get a category nested facet. In this example, you specify a maximum to limit the number of facet values returned.
{
"facet": {
"category_tree":
{"max": 5}
}
}The following code shows the corresponding response:
{
"ts": 1480977544,
"rid": "response_id_f3",
"facet": {
"category_tree": {
"value": [
{
"id": "ct1",
"text": "Mens",
"count": 5,
"sub": [
{"id": "ct11", "text": "Shirt", "count": 2},
{"id": "ct12", "text": "Pants", "count": 3}
]
},
{
"id": "ct2",
"text": "Womens",
"count": 2,
"sub": [
{"id": "ct21", "text": "Shirt", "count": 1},
{"id": "ct22", "text": "Pants", "count": 1}
]
},
{
"id": "ct3",
"text": "Kids",
"count": 5,
"sub": [
{"id": "ct31", "text": "Shirt", "count": 5}
]
}
]
}
},
"facet_names": ["category_tree"]
}The max applies to all facet values under sub.
sub indicates the list of subfacets that belong to the facet. This is useful to represent a hierarchical structure such as a category tree. In the example, there are three shirt categories that belong to different parent categories (Mens, Womens, and Kids).
Getting the top facet values from a dynamic attributes collection
The following code shows a request to get the top three values for the color and clothing_type facets from a dynamic attributes collection.
The dyn_attrs key is a dynamic attribute enabled for the facet.
{
"facet": {
"dyn_attrs": {"max": 3}
}
}The following code shows the corresponding response:
{
"ts": 1480977544,
"rid": "response_id_f1",
"facet": {
"dyn_attrs.color": {
"number_of_products": 8762,
"display_name": "Color",
"value": [
{"count": 913, "text": "Black", "id": "facet_idQmxhY2s=", "in_content": "product"},
{"count": 532, "text": "Yellow", "id": "facet_idWWVsbG93", "in_content": "product"},
{"count": 378, "text": "Green", "id": "facet_idR3JlZW4=", "in_content": "product"}
]
},
"dyn_attrs.clothing_type": {
"number_of_products": 3139,
"display_name": "Clothing Type",
"value": [
{"count": 229, "text": "Pants", "id": "facet_idUGFudHM=", "in_content": "product"},
{"count": 418, "text": "Coveralls", "id": "facet_idQ292ZXJhbGxz", "in_content": "product"},
{"count": 233, "text": "Jackets", "id": "facet_idSmFja2V0cw==", "in_content": "product"}
]
}
},
"facet_names": [
"dyn_attrs.material",
"dyn_attrs.color",
"dyn_attrs.clothing_type"
]
}Getting all values for a specific attribute from a dynamic attributes collection
The following code shows a request to get all values for a specific attribute (clothing_type) from a dynamic attributes collection.
The dyn_attrs.clothing_type key is an individual attribute (clothing_type) within a dynamic attribute (dyn_attrs) enabled for the facet.
{
"facet": {
"dyn_attrs.clothing_type": {"max": 100}
}
}The following code shows the corresponding response:
{
"ts": 1480977544,
"rid": "response_id_f1",
"facet": {
"dyn_attrs.clothing_type": {
"number_of_products": 1441,
"display_name": "Clothing Type",
"value": [
{"count": 234, "text": "Pants", "id": "facet_idUGFudHM=", "in_content": "product"},
{"count": 441, "text": "Coveralls", "id": "facet_idQ292ZXJhbGxz", "in_content": "product"},
{"count": 240, "text": "Jackets", "id": "facet_idSmFja2V0cw==", "in_content": "product"},
{"count": 307, "text": "Shirts", "id": "facet_idU2hpcnRz", "in_content": "product"},
{"count": 219, "text": "Safety Vests", "id": "facet_idU2FmZXR5IFZlc3Rz", "in_content": "product"},
...
]
}
},
"facet_names": [
"dyn_attrs.color"
]
}