The facets field enables the retrieval of facets. Facets are values in fields that which can be used to navigate through the results by filtering.
Fields used for faceting are suggested in the autocomplete of the GraphQL user interface. You can specify multiple fields and nested fields for faceting.
Note
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 and Bool fields
For each string or bool (filter) field, there are four optional parameters for each field:
`
orderType` – By COUNT (default) or by VALUE.`
orderBy` – Specifies ASC or DESC (default) order of the facets.`
limit` – Specifies up to 1000 facets to retrieve (default: 10).`
filters` – Specifies the facets that should be applied with the field. This can be a list of string values. This is used to support multi-select of facets, such as applying a facet as a filter to update the list of results, while preserving the list of original facets but get updated hit counts for the `items` and facets without `filters`. In case the value of `filters` is an empty string `""`, then it will be ignored.
Filters in the string fields are used to support multi-select
There are cases where multiple facets within a field should be selectable and be applied (such as using checkboxes), where the original facets should persist so more facets can be enabled or disabled while only updating the result list and other facets.
How does multi-select of facets work? The following example is by [courtesy of Yonik Seely](🔗). Suppose you have the following fields with facets:
If you select the facet `
Blue`, then you get the updated view, where the other facets are updated and the search results, but the original `Color` facets stay the same so they can be turned on or off.If you also select black, then you get this updated view:
The search results are expanded with the extra added filter in `
Color` and the facet counts in the other fields.
The facets are projected by:
`
name` – Shows the name of the facet, which is the value that can be faceted on.`
count` – Shows the facet count, which is the number of hits that would match with the name.
Request with string example:
The following code returns the facets as part of the facets projection:
Request example with multi-select of facets using `filters`, where only the items and counts of facets are updated, while preserving the list of facets:
The following code returns all original facets with orginal facet counts and the new updated result list that applies `VideoFile` to `ContentType`, resulting in 32 `items`:
An example of using `filters` for a multi-select request with `Bool` field example.
The following code returns facets with value equal to `True`.
Use only matching values for `
filters`Enter valid values for `
filters`. For example, note that there are only two possible values for `Boo`l fields: true and false. Therefore, if a string value that is other than those two possible values is inserted, the results will be empty.
## Date fields
You can retrieve the facets of date fields 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 (default: 1)`
unit` – The unit of time. MINUTE, HOUR, or DAY (default).
Request example where you drop the items from the response and only project the facets:
The following code response does the bucketing of documents with the Created field by 14 days (bi-weekly):
## Number fields
For each number (filter) field, there is a `ranges` parameter and this parameter is array of objects that has two optional parameters:
`
from` – The minimum (lowerbound) value in range. This can be nullable.`
to` – The maximum (upperbound) value in range. The upperbound value is treated as non-inclusive, so the `to` value always needs to be higher than the `from` value to return results. This is indicated with the notation of the bucket name like `[10,100)` (starting with square bracket and ending with parenthesis). This can be nullable.
Request example:
The following code returns the facets as part of the extensions section of the response:
## Combine facet types
You can request a mixture of (multiple) different field types in the facets projection, letting you retrieve multiple facets of different fields in a single request.
Request example: