Skip to main content

Using faceted search

Abstract

Learn how to use the Search and Recommendation API for Sitecore Search to get search results with facets.

To request a facet, add a widget.items.search.facet object to your request.

For the data model of this object, see the Search and Recommendation API reference.

The following sections show sample requests to get a response with facets.

To get all available facets, set the all key to true.

The following is a sample request:

{
    "widget": {
        "items": [
            {
                "rfk_id": "rfkid_7",
                "entity": "content",
                "search": {
                    "facet": {
                        "all": true
                    }
                }
            }
        ]
    },
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        },
        "user": {
            "uuid": "159871551-io-0i-4e-1p-s6ill6vhenvysbu27bbk-1664389956369"
        }
    }
}

The following is the response to this request:

{
    "widgets": [
        {
            "rfk_id": "rfkid_7",
            "entity": "content",
            "facet": [
                {
                    "name": "product",
                    "label": "Product",
                    "value": [
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiRXhwZXJpZW5jZSBQbGF0Zm9ybSAoWFApIn0=",
                            "text": "Experience Platform (XP)",
                            "count": 130
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiRXhwZXJpZW5jZSBNYW5hZ2VyIChYTSkifQ==",
                            "text": "Experience Manager (XM)",
                            "count": 80
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiQ29udGVudCBIdWIifQ==",
                            "text": "Content Hub",
                            "count": 73
                        }
                        ...
                    ]
                },
                {
                    "name": "type",
                    "label": "Type",
                    "value": [
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoidHlwZSIsInZhbHVlIjoib3RoZXIifQ==",
                            "text": "other",
                            "count": 990
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoidHlwZSIsInZhbHVlIjoibmV3cyJ9",
                            "text": "news",
                            "count": 623
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoidHlwZSIsInZhbHVlIjoiQmxvZ3MifQ==",
                            "text": "Blogs",
                            "count": 519
                        }
                        ...
                    ]
                }
            ]
        }
    ],
    "dt": 62,
    "ts": 1669437158552
}

In the response facet object, you can see that the two available facets, product and type appear. Each facet array has objects for the facet values within that facet type.

To get some values for a facet, pass the name of the facet and then pass the number of values you want as the max number of values you want.

For example, you want to show five values for the product facet. The following is a sample request:

{
    "widget": {
        "items": [
            {
                "rfk_id": "rfkid_7",
                "entity": "content",
                "search": {
                    "facet": {
                        "types": [
                            {
                                "name": "product",
                                "max": 5
                            }
                        ]
                    }
                }
            }
        ]
    },
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        },
        "user": {
            "uuid": "159871551-io-0i-4e-1p-s6ill6vhenvysbu27bbk-1664389956369"
        }
    }
}

The following is the response to this request:

{
    "widgets": {
        "rfkid_7": {
            "facet": {
                "product": {
                    "label": "Product",
                    "value": [
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiRXhwZXJpZW5jZSBQbGF0Zm9ybSAoWFApIn0=",
                            "text": "Experience Platform (XP)",
                            "count": 137
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiRXhwZXJpZW5jZSBNYW5hZ2VyIChYTSkifQ==",
                            "text": "Experience Manager (XM)",
                            "count": 83
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiQ29udGVudCBIdWIifQ==",
                            "text": "Content Hub",
                            "count": 73
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiQ3VzdG9tZXIgRGF0YSBQbGF0Zm9ybSJ9",
                            "text": "Customer Data Platform",
                            "count": 68
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoicHJvZHVjdCIsInZhbHVlIjoiT3JkZXJDbG91ZCJ9",
                            "text": "OrderCloud",
                            "count": 35
                        }
                    ]
                }
            }
        }
    },
    "dt": 38,
    "ts": 1666323029989
}

In the response facet object, you can see one facet, Product with five values.

To get the top values from a dynamic attributes collection, pass the dynamic attribute collection name as the name. You can also pass a max value to specify how many values you want to see.

For example, you want to see the top five values from the attribute_tags dynamic attribute collection. The following is a sample request:

{
    "widget": {
        "items": [
            {
                "rfk_id": "rfkid_7",
                "entity": "product",
                "search": {
                    "facet": {
                        "types": [
                            {
                                "name": "attribute_tags",
                                "max": 5
                            }
                        ]
                    }
                }
            }
        ]
    },
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        }
    }
}

The following is the response to this request:

{
    "widgets": [
        {
            "rfk_id": "rfkid_7",
            "entity": "product",
            "facet": [
                {
                    "name": "attribute_tags.ID13",
                    "label": "Material",
                    "value": [
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNyIsInZhbHVlIjoiVGV4dGlsZSJ9",
                            "text": "Textile",
                            "count": 3135
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNyIsInZhbHVlIjoiUGxhc3RpYyJ9",
                            "text": "Plastic",
                            "count": 2852
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNyIsInZhbHVlIjoiQWx1bWludW0ifQ==",
                            "text": "Aluminum",
                            "count": 2691
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNyIsInZhbHVlIjoiUG9seWVzdGVyIn0=",
                            "text": "Polyester",
                            "count": 2220
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNyIsInZhbHVlIjoiTGVhdGhlciJ9",
                            "text": "Leather",
                            "count": 2109
                        }
                    ]
                },
                {
                    "name": "attribute_tags.ID354",
                    "label": "Type - Engine",
                    "value": [
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzNTYiLCJ2YWx1ZSI6IlR3aW4gQ2FtIFN0eWxlIn0=",
                            "text": "Twin Cam Style",
                            "count": 23137
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzNTYiLCJ2YWx1ZSI6IkV2b2x1dGlvbiBTdHlsZSJ9",
                            "text": "Evolution Style",
                            "count": 14384
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzNTYiLCJ2YWx1ZSI6Ik1pbHdhdWtlZS1FaWdodCAxMDcifQ==",
                            "text": "Milwaukee-Eight 107",
                            "count": 13086
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzNTYiLCJ2YWx1ZSI6Ik1pbHdhdWtlZS1FaWdodCAxMTQifQ==",
                            "text": "Milwaukee-Eight 114",
                            "count": 12629
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzNTYiLCJ2YWx1ZSI6Ik1pbHdhdWtlZS1FaWdodCAxMTcgICJ9",
                            "text": "Milwaukee-Eight 117  ",
                            "count": 10246
                        }
                    ]
                },
                {
                    "name": "attribute_tags.ID2",
                    "label": "Color",
                    "value": [
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzIiwidmFsdWUiOiJCbGFjayJ9",
                            "text": "Black",
                            "count": 45536
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzIiwidmFsdWUiOiJHcmF5In0=",
                            "text": "Gray",
                            "count": 7904
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzIiwidmFsdWUiOiJCbHVlIn0=",
                            "text": "Blue",
                            "count": 6628
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzIiwidmFsdWUiOiJDaHJvbWUifQ==",
                            "text": "Chrome",
                            "count": 5021
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQzIiwidmFsdWUiOiJXaGl0ZSJ9",
                            "text": "White",
                            "count": 4843
                        }
                    ]
                }
                ...
            ]
        }
    ],
    "dt": 31,
    "ts": 1669044364271
}

In the response facet object, you can see two facet types, attribute_tags.ID136 (U.S. size) and attribute_tags.ID138 (gender), with many values in each.

To get specific attributes from a dynamic attributes collection, pass the names of the specific attribute you want.

For example, you want to get the attribute_tags.ID18 and attribute_tags.ID12 attributes from the attribute_tags dynamic attribute collection. The following is a sample request:

{
    "widget": {
        "items": [
            {
                "rfk_id": "rfkid_7",
                "entity": "product",
                "search": {
                    "facet": {
                        "types": [
                            {
                                "name": "attribute_tags.ID18"
                            },
                            {
                                "name": "attribute_tags.ID12"
                            }
                        ]
                    }
                }
            }
        ]
    },
    "context": {
        "locale": {
            "country": "us",
            "language": "en"
        }
    }
}

The following is the response to this request:

{
    "widgets": [
        {
            "rfk_id": "rfkid_7",
            "entity": "product",
            "facet": [
                {
                    "name": "attribute_tags.ID18",
                    "label": "U.S. Size",
                    "value": [
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxMyIsInZhbHVlIjoiTWVkaXVtIn0=",
                            "text": "Medium",
                            "count": 5166
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxMyIsInZhbHVlIjoiTGFyZ2UifQ==",
                            "text": "Large",
                            "count": 5003
                        }, 

            ...
                    ]
                },
                {
                    "name": "attribute_tags.ID12",
                    "label": "Size",
                    "value": [
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNSIsInZhbHVlIjoiTGFyZ2UifQ==",
                            "text": "Large",
                            "count": 2513
                        },
                        {
                            "id": "facetid_eyJ0eXBlIjoiZXEiLCJuYW1lIjoiYXR0cmlidXRlX3RhZ3MuSUQxNSIsInZhbHVlIjoiTWVkaXVtIn0=",
                            "text": "Medium",
                            "count": 2476
                        }, 

            ...
                    ]
                }
            ]
        }
    ],
    "dt": 531,
    "ts": 1669044284670
}