This topic 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.
How it works
The facets field enables the retrieval of facets. Facets are values in fields that are a concept, which can be used to navigate through the results by filtering.
Fields that can be used for faceting will be suggested in the autocomplete of the GraphiQL user interface. Multiple fields can be specified can be selected for faceting. Nested fields can also be used for faceting.
Tip: In case only the facets should be returned, but no results, the limit parameter in the where field has to be set to 0. This will significantly improve the query times.
String fields
For each string (filter) field, there are 3 optional parameters for each field:
- orderType. This can be by COUNT or VALUE (default: COUNT).
- orderBy. Specifies the order of the facets. This can be either in ASC or DESC order (default: DESC)
- limit. Specifies the number of facets to retrieve (default: 10). This cannot be greater than 1,000 or an error message will be shown.
The facets are projected by
- name. This field shows the name of the facet, i.e. the value that can be faceted on.
- count. This fields shows the facet count, i.e. the number of hits that would match with the name.
Request example:
query MyQuery {
StandardPage (limit: 1) {
items {
RouteSegment
Saved
}
facets {
RouteSegment (limit: 8, orderType: VALUE, orderBy: ASC) {
name
count
}
}
}
}
This will return 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
}
]
}
Date fields
The facets of date fields can be retrieved as a histogram, where the latest 1,000 units of value are retrieved. For each date field, there are two optional parameters:
- value. The quantity for the unit. It can be an integer. By default it is
1.
- unit. The unit of time. This can be MINUTE, HOUR, or DAY, where DAY is default.
Request example where we drop the items from the response and only project the facets:
query MyQuery {
StandardPage (limit: 0) {
facets {
Created (unit: DAY, value: 14) {
name
count
}
}
}
}
This response will do 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
For each number (filter) field, there is a ranges parameter and this parameter is array of objects that has 2 optional parameters:
- from. The minimum value in range. This can be nullable.
- to. The maximum value in range. This can be nullable.
Request example:
query MyQuery {
StartPage {
items {
Visitor
}
facets {
Visitor(ranges: [{from: 10, to: 100}, {from: 1000}, {to: 100000}])
}
}
}
This will return the facets as part of the extensions section of the response:
"data": {
"StandardPage": {
"items": [...],
"facets": {
"Visitor": [
{
"[,100000]": 1
},
{
"[10,100]": 1
},
{
"[1000,]": 0
}
]
}
}
}
We can request a mixture of (multiple) different field types in the facets projection, allowing us to retrieve multiple facets of different fields in a single request.
Request example:
query MyQuery {
Content {
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
}
}
}
}
}
Related topics
Last updated: Jun 28, 2021
