Facets (also called aggregations) build a particular view over a set dataset. For example, you can see how many documents were created by each user, how many documents fall in a given creation date range, and get the highest value in a set of documents.
query {
search(q: "jahia") {
termFacet(field: "jgql:createdBy") {
data {
count
value
disjunctive facets
When allowing visitors to explore a dataset, you often need to enable disjunctive facets, which build an aggregation excluding any existing filters on the facet's current field.
In other words, if your dataset is about movies, you would probably want a "genre" facet:
If your facet is conjunctive, a visitor clicking on "Comedy" will see results filtered on that particular genre, but will not be able to select another genre in the facet.
If your fact is disjunctive, a visitor clicking on "Comedy" will see results filtered on that particular genre and how many documents match other genres, such as "Horror". This makes it possible to build user interfaces allowing queries such as "movie genre is Comedy or Horror".
minDocCount
There might be occurrences in which an aggregation can generate a lot of results with only a few documents, while your users might only be interested in the ones with most results. Specifying the
minDocCount
parameter only returns results containing at least the specified number of documents. Note that prior to version 3.0, the default value for
minDocCount
was 5, compared to 1 in newer versions.
missingValue
In some occurrences, the aggregated field might not have a value, but the absence of a value is still a relevant piece of information. In such a case, you can specify a missing value to return when there is no value in the dataset.
For example, a movie database might have a field detailing the primary country in which the movie is taking place. This field would be empty for movies taking place in space. The resulting query would look like this:
query {
search(q: "brad pitt") {
termFacet(field: "movieCountry", missingValue: "space") {
data {
count
value
treeFacet
The
treeFacet
node provides a very similar feature but supports hierarchical use cases, for example, building a hierarchy such as Continent>Country>Region>City, to return the number of documents matching each of these elements. You can do this by providing the
rootPath
parameter.
Each aggregation then contains a
hasChildren
field to indicate whether the value under
rootPath
contains children.
search(q: "") {
treeFacet(field: "jgql:categories_path.facet", rootPath: "/music") {
data {
count
value
hasChildren
rootPath
field
rootPath
Which would return this payload:
"data": {
"search": {
"treeFacet": {
"data": [
"count": 2,
"value": "classical",
"hasChildren": false,
"rootPath": "/music/classical"
"count": 2,
"value": "electronic",
"hasChildren": true,
"rootPath": "/music/electronic",
"count": 1,
"value": "blues",
"hasChildren": true,
"rootPath": "/music/blues",
"field": "jgql:categories_path.facet",
"rootPath": "/music"
In the above payload, notice that both "
electronic
" and "
blues
" have children. You could therefore run the query again, passing "
/music/electronic
" as
rootPath
to fetch all elements under "
electronic
".
rangeFacet
The
rangeFacet
created data buckets based on user specified date or number ranges. Support for the
date math expression
allows you to create of buckets based on fixed dates or automatically generated from today's date.
The query below is an example mixing both fixed dates and date math expressions (although such query has a limited practical use).
query {
search(q: "") {
created: rangeFacet(
field: "jcr:created"
ranges: [
{ from: "2015-01-01", to: "2015-12-31", name: "2015" }
{ from: "2016-01-01", to: "2016-12-31", name: "2016" }
{ from: "now-1y", to: "now", name: "Last year" }
data {
count
