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.
Augmented Search supports the following facets:
The termFacet
aggregates documents for each unique value of a specified field. For example, the query below returns the number of documents per author.
query {
search(q: "jahia") {
termFacet(field: "jgql:createdBy") {
data {
count
value
}
}
}
}
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:
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.
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
}
}
}
}
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".
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 {
name
count
}
}
}
}
This will produce the following result:
{
"data": {
"search": {
"created": {
"data": [
{
"name": "2015",
"count": 0
},
{
"name": "2016",
"count": 137
},
{
"name": "Last year",
"count": 7
}
]
}
}
}
}
The numberRange
facet, given a numerical field, provides access to max
and min
values for that field across the entire dataset.