Facets
The facets field retrieves facets, the values in fields that readers use to filter results. This pattern is called faceted search and helps visitors narrow large result sets to the items most relevant to them.
The GraphQL UI autocomplete suggests fields used for faceting. Specify multiple fields and nested fields for faceting.
📘 Note To return only the facets when no results exist, set the limit parameter in the where field to 0. This improves query times.
String and bool fields
The facets projection accepts string and bool fields when you want categorical filters such as content type, tag, or a yes-or-no flag. Use the parameters in this section to control the order, count, and active selection of the facet values returned.
Each string or bool (filter) field accepts four optional parameters:
- orderType – By COUNT (default) or by VALUE. When sorting by VALUE, sorting follows lexicographical order. For example, capital letters have a lower value than lowercase letters.
- orderBy – Specifies ASC or DESC (default) order of the facets.
- limit – Specifies up to 1000 facets to retrieve (default: 10).
- filters – Specifies the facets to apply with the field. This is a list of string values that supports multi-select of facets. Apply a facet as a filter to update the result list while preserving the original facets. The items and the facets without filters show updated hit counts. If the value of filters is an empty string "", the system ignores it.
📘 Note Multiple facets within a field can be selectable and applied (such as using checkboxes), where the original facets persist so more facets can be enabled or disabled while only updating the result list and other facets.
The following example by courtesy of Yonik Seely shows how a multi-select of facets works. Suppose you have the following fields with facets:
=== Size === === Color === === Brand ===
[Small] (7) [ ] Red (2) [ ] Nike (7)
[Medium] (5) [ ] Blue (8) [ ] Adidas (5)
[Large] (6) [ ] Green (3) [ ] Reebok (4)
[ ] Black (5) [ ] Under Armour (2)When you select the facet Blue, the updated view shows the other facets and the search results refreshed, but the original Color facets stay the same, so you can turn them on or off.
=== Size === === Color === === Brand ===
[Small] (3) [ ] Red (2) [ ] Nike (3)
[Medium] (2) [x] Blue (8) [ ] Adidas (2)
[Large] (3) [ ] Green (3) [ ] Reebok (2)
[ ] Black (5) [ ] Under Armour (1)
(Top Blue running shorts displayed here)When you also select black, the following updated view appears:
=== Size === === Color === === Brand ===
[Small] (5) [ ] Red (2) [ ] Nike (5)
[Medium] (4) [x] Blue (8) [ ] Adidas (3)
[Large] (4) [ ] Green (3) [ ] Reebok (3)
[x] Black (5) [ ] Under Armour (2)
(Top Blue and Black running shorts displayed here)The search results are expanded with the extra added filter in Color and the facet counts in the other fields.
Project each facet with the following two fields:
- name – Shows the facet's name, which is the value that can be faceted on.
- count – Shows the facet count, which is the number of hits that match the name.
The following is a request with a string example:
query MyQuery {
StandardPage (locale: en, limit: 1) {
items {
RouteSegment
Saved
}
facets {
RouteSegment (limit: 8, orderType: VALUE, orderBy: ASC) {
name
count
}
}
}
}The following code returns the facets as part of the facets projection:
"facets": {
"RouteSegment": [
{
"name": "about-us",
"count": 1
},
{
"name": "become-a-reseller",
"count": 1
},
{
"name": "collaboration-made-simple",
"count": 1
},
{
"name": "contact-us",
"count": 1
},
{
"name": "download-whitepaper-alloy-track",
"count": 1
},
{
"name": "find-a-reseller",
"count": 1
},
{
"name": "management",
"count": 1
},
{
"name": "news-events",
"count": 1
}
]
}The following is a request example with multi-select of facets using filters, where only the items and counts of facets update while preserving the list of facets:
{
Content(locale: en, limit: 1) {
items {
_score
Name
ContentType
}
total
facets {
ContentType(filters: ["ImageFile"]) {
name
count
}
}
}
}The following code returns all original facets with original facet counts and the new updated result list that applies VideoFile to ContentType, resulting in 32 items:
{
 "data": {
   "Content": {
     "items": [
       {
         "_score": 0,
         "Name": "ToddSlayton.jpg",
         "ContentType": [
           "Image",
           "Media",
           "ImageFile",
           "Content"
         ]
       }
     ],
     "total": 32,
     "facets": {
       "ContentType": [
         {
           "count": 89,
           "name": "Content"
         },
         {
           "count": 34,
           "name": "Page"
         },
         {
           "count": 33,
           "name": "Media"
         },
         {
           "count": 32,
           "name": "Image"
         },
         {
           "count": 32,
           "name": "ImageFile"
         },
         {
           "count": 22,
           "name": "Block"
         },
         {
           "count": 12,
           "name": "StandardPage"
         },
         {
           "count": 8,
           "name": "PageListBlock"
         },
         {
           "count": 5,
           "name": "ContactPage"
         },
         {
           "count": 5,
           "name": "TeaserBlock"
         }
       ]
     }
   }
 },
 "extensions": {
   "correlationId": "f3c1dd78-5a01-4595-a3ef-a0065a1e0f28"
 }
}The following is an example of using filters for a multi-select request with a Bool field:
query MyQuery {
AllPropertiesTestPage(locale: en) {
facets {
Boolfield(filters: "true") {
name
count
}
}
items {
Name
Boolfield
}
}
}The following code returns facets with a value equal to True.
📘 Note Enter valid values for filters. Bool fields have only two possible values: true and false. If a string value other than these two possible values is inserted, the results are empty.
{
"data": {
"AllPropertiesTestPage": {
"facets": {
"Boolfield": [
{
"name": "true",
"count": 1
}
]
},
"items": [
{
"Boolfield": true
}
]
}
}
}Date fields
Date facets return a histogram so that visitors can filter results by time bucket, such as items created in the last 14 days. Use the parameters in this section to control the unit and the quantity of each bucket.
Retrieve the facets of date fields as a histogram, where the system returns the latest 1,000 units of value.
📘 Note Date facets only return units with matching items. Only date facets with at least one matching item display to reduce the response size.
Each date field has two optional parameters:
- value – The quantity for the unit. It can be an integer (default: 1).
- unit – The unit of time. MINUTE, HOUR, or DAY (default).
The following example request drops the items from the response and only projects the facets:
query MyQuery {
StandardPage (locale: en, limit: 0) {
facets {
Created (unit: DAY, value: 14) {
name
count
}
}
}
}The following code response performs the bucketing of documents with the Created field by 14 days (bi-weekly):
"data": {
"StandardPage": {
"facets": {
"Created": [
{
"2012-08-02T00:00:00Z": 1
},
{
"2012-08-16T00:00:00Z": 2
},
{
"2012-08-30T00:00:00Z": 2
},
{
"2012-09-13T00:00:00Z": 2
},
{
"2012-09-27T00:00:00Z": 3
}
]
}
}
}Number fields
Number facets group numeric values into ranges, such as price brackets or visitor counts, so that visitors can filter results by quantitative criteria. Use the ranges parameter to define each bucket, or treat number facets as categories when the property holds discrete values.
📘 Note Number facets behave like the String typeString type when the property is categorical data, such as a shoe size. To get facets for the number type as categories, add any of the following categorical parameters: orderType, orderBy, limit, or filters.
By default, the field uses the ranges parameter. When ranges is combined with the categorical parameters, the categorical facets take precedence.
Each number (filter) field has a ranges parameter, which is an array of objects with two optional parameters:
- from – The minimum (lower bound) value in the range. This can be null.
- to – The maximum (upper bound) value in the range. The upper bound value is treated as non-inclusive, so the to value must be higher than the from value to return results. This is indicated with the notation of the bucket name, like [10,100) (starting with a square bracket and ending with parenthesis). This can be null.
The following is a request example:
query MyQuery {
StartPage(locale: en) {
items {
Visitor
}
facets {
Visitor(ranges: [{from: 10, to: 100}, {from: 1000}, {to: 100000}])
}
}
}The following code returns the facets as part of the extensions section of the response:
"data": {
"StandardPage": {
"items": [...],
"facets": {
"Visitor": [
{
"[,100000)": 1
},
{
"[10,100)": 1
},
{
"[1000,)": 0
}
]
}
}
}Combine facet types
Combine string, bool, date, and number facets in a single request when the search experience needs filters across several content attributes at once, such as a content type filter beside a date histogram and a price range.
In the facets projection, request multiple field types to retrieve facets for several fields in a single request.
The following is a request example:
query MyQuery {
Content(locale: en) {
items {
Name
Changed
ContentLink {
Id
}
}
facets {
Changed(unit: DAY, value: 100) {
name
count
}
Name(limit: 10, orderBy: ASC, orderype: VALUE) {
name
count
}
ContentLink {
Id(ranges: [{from: 10, to: 100}, {from: 1000}]) {
name
count
}
}
}
}
}