Facets
Describes the facets field, part of the GraphQL API used for the Optimizely querying service, when retrieving faceted content in Optimizely solutions. It is a sibling field of items, which contain the matching hits.
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.
NoteTo return only the facets when no results exist, set the
limitparameter 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 byVALUE. When sorting byVALUE, sorting follows lexicographical order. For example, capital letters have a lower value than lowercase letters. - orderBy – Specifies
ASCorDESC(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
itemsand the facets withoutfiltersshow updated hit counts. If the value offiltersis an empty string"", the system ignores it.
NoteMultiple 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 originalColorfacets 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
Colorand 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.
NoteEnter valid values for
filters. Bool fields have only two possible values:trueandfalse. 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 time unit and the period the histogram covers.
Retrieve the facets of date fields as a histogram, where the system returns up to the latest 1,000 buckets.
NoteDate 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:
- unit – The unit of time.
MINUTE,HOUR,DAY(default),MONTH, orYEAR. - value – An integer. Its meaning depends on the unit:
- For
MINUTE,HOUR, andDAY,valuesets the width of each bucket in that unit (default:1). For example,unit: DAY, value: 14returns 14-day buckets. - For
MONTHandYEAR,valuesets how many units to look back (default and maximum:1000). For example,unit: MONTH, value: 24returns monthly buckets for the last 24 months.
- For
MONTH and YEAR are calendar units. Each bucket is one calendar month or one calendar year wide. For these units, value sets the length of the period, not the bucket width. Buckets align to the first day of the month or year. Because the buckets follow the calendar, they absorb varying month lengths and leap years. Optimizely Graph returns an invalid-argument error when value exceeds 1000 for these units.
MINUTE, HOUR, and DAY are fixed-length units, so value widens each bucket instead.
Choose MONTH or YEAR for content that spans many years. A date facet returns at most 1,000 buckets, so single-day buckets reach back less than three years. Monthly buckets reach back about 83 years, and yearly buckets reach back 1,000 years.
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
}
]
}
}
}Group date facets by month or year
Use MONTH or YEAR when content spans a period too long to bucket by day. The following request returns monthly buckets for the last 24 months:
query MyQuery {
StandardPage (locale: en, limit: 0) {
facets {
Created (unit: MONTH, value: 24) {
name
count
}
}
}
}Each bucket name is the first day of the month:
"data": {
"StandardPage": {
"facets": {
"Created": [
{
"2023-05-01T00:00:00Z": 4
},
{
"2023-06-01T00:00:00Z": 7
},
{
"2023-07-01T00:00:00Z": 2
}
]
}
}
}To bucket by year, use unit: YEAR. When you omit value, the facet looks back the maximum 1,000 units:
query MyQuery {
StandardPage (locale: en, limit: 0) {
facets {
Created (unit: YEAR) {
name
count
}
}
}
}Each bucket name is the first day of the year:
"data": {
"StandardPage": {
"facets": {
"Created": [
{
"2023-01-01T00:00:00Z": 31
},
{
"2024-01-01T00:00:00Z": 48
},
{
"2025-01-01T00:00:00Z": 22
}
]
}
}
}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.
NoteNumber facets behave like the String 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, orfilters.By default, the field uses the
rangesparameter. Whenrangesis 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
tovalue must be higher than thefromvalue 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
}
}
}
}
}Updated 12 days ago