Facets

14 min

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

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:

unit – The unit of time. MINUTE, HOUR, DAY (default), MONTH, or YEAR.

value – An integer. Its meaning depends on the unit:

For MINUTE, HOUR, and DAY, value sets the width of each bucket in that unit (default: 1). For example, unit: DAY, value: 14 returns 14-day buckets.

For MONTH and YEAR, value sets how many units to look back (default and maximum: 1000). For example, unit: MONTH, value: 24 returns monthly buckets for the last 24 months.

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.

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
        }
      }
    }
  }
}