---
title: "Using faceted search"
slug: "using-faceted-search"
abstract: "Basic examples of how to use the Discover Search and Recommendation API to perform faceted search"
---
# 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](https://doc.sitecore.com/discover/en/developers/discover-developer-guide/integrate-using-discover-rest-apis/integrate-using-the-search-and-recommendation-api/examples-of-basic-search-and-recommendation-use-cases/the-facet-request-object.md "The facet request object") to view the request data structure or see [advanced use cases](https://doc.sitecore.com/discover/en/developers/discover-developer-guide/integrate-using-discover-rest-apis/integrate-using-the-search-and-recommendation-api/examples-of-basic-search-and-recommendation-use-cases/examples-of-advanced-search-and-recommendation-use-cases.md "Examples of advanced search and recommendation use cases") for more examples.

> [!note]
> In addition to the examples here, you can also [filter facets](https://doc.sitecore.com/discover/en/developers/discover-developer-guide/integrate-using-discover-rest-apis/integrate-using-the-search-and-recommendation-api/examples-of-basic-search-and-recommendation-use-cases/using-search-filters.html#UUID-13adc50c-7c0b-6963-49c1-6f9d0853c679_section-idm457337767301763287780843066 "Filters for different facet types").

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

```JSON
{
  "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:

```JSON
{
  "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](https://doc.sitecore.com/discover/en/developers/discover-developer-guide/integrate-using-discover-rest-apis/integrate-using-the-search-and-recommendation-api/examples-of-basic-search-and-recommendation-use-cases/sorting-facets.md "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.

```JSON
{
  "facet": {
    "colors": {"max": 100}
  }
}
```

The following code shows the corresponding response:

```JSON
{
  "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.

```JSON
{
  "facet": {
    "price": {"max": 3}
  }
}
```

The following code shows the corresponding response:

```JSON
{
  "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.

```JSON
{
  "facet": {
    "category_tree":
{"max": 5}
  }
}
```

The following code shows the corresponding response:

```JSON
{
  "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"]
}
```

> [!note]
> 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.

```JSON
{
  "facet": {
    "dyn_attrs": {"max": 3}
  }
}
```

The following code shows the corresponding response:

```JSON
{
  "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.

```JSON
{
  "facet": {
    "dyn_attrs.clothing_type": {"max": 100}
  }
}
```

The following code shows the corresponding response:

```JSON
{
  "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"
  ]
}
```