Aggregations can be requested when querying items. They are used to calculate summarized views and statistics about the data in a search results. This allows you to build data drill-downs along the structured part of items as well as visualizations over time or other data dimensions.
Table of Contents
Table of Contents |
---|
outline | true |
---|
exclude | Table of Contents |
---|
|
Specification
The request format is an url encoded JSON object of the following format:
Code Block |
---|
|
{<field_or_label>:
{
["fields": <field_name> | <list of field_names>]
[, "size": <number of results>]?
[, "method": <metric_function>]?
[, "interval": <interval>]?
[, "aggregation": <field name>]?
}
[, <field_or_label> : {
...
}]
} |
- field_or_label – may be a label to group multiple aggregations by specifying fields inside the aggregation dictionary. If no fields are provided, the label is used as fields.
- fields – can be any of
- all – all facets
- language – item language
- source – source field
- provider – provider field
- $<field> – :item field named
- other value – mapped to a facet field with the corresponding name
- aggregation – in the same format for specifying lower dimension aggregations.
- size – an integer specifying the number of aggregation results to return. Only supported for method terms and significant_terms. The default size is 10.
- method – a method name to aggregate number type return values. Defaults to terms. Available methods are:
- terms
- significant_terms
- histogram
- interval – an interval for histograms. Only supported for method histogram. For date_time type facets the available intervals are: year, quarter, month, week, day, hour, minute, second.
The response is returned in the following format:
Code Block |
---|
|
{
"aggregations": {
"<label>": {
"<field_name>": {
"values": [
{"key": "value1", "value": 11},
{"key": "value2", "value": 9},
.....
]
}
}
}
} |
or for numerically aggregated values:
Code Block |
---|
|
{
"aggregations": {
"<label>": {
"<field_name>": {
"values": [
{"value": 11}
]
}
}
}
} |
Aggregations can be nested, in which case the response will be nested as well:
Code Block |
---|
|
{
"aggregations": {
"<label>": {
"<field_name>": {
"values": [
{
"key": "value1",
"value": 11,
"values": [
{
"key": "sub_value1",
"value": 7
},
{
"key": "sub_value2",
"value": 4
}
]
}, {
"key": "value2",
"value": 9
"values": [
{
"key": "sub_value1",
"value": 6
},
{
"key": "sub_value2",
"value": 3
}
]
},
.....
]
}
}
}
} |
When selecting multiple labels, the output will contain responses for each of the labels:
Code Block |
---|
|
{
"aggregations": {
"<label1>": {
"<field_name1>": {
"values": [
{"key": "value1", "value": 11},
{"key": "value2", "value": 9},
.....
]
}
}
"<label2>": {
"<field_name2>": {
"values": [
{"key": "value1", "value": 11},
{"key": "value2", "value": 9},
.....
]
}
}
}
} |
If one label contains multiple fields, the response will contain a section for each field below the label:
Code Block |
---|
|
{
"aggregations": {
"<label>": {
"<field_name1>": {
"values": [
{"key": "value1", "value": 11},
{"key": "value2", "value": 9},
.....
]
},
"<field_name2>": {
"values": [
{"key": "value3", "value": 7},
{"key": "value4", "value": 5},
.....
]
}
}
}
} |
Code Block |
---|
|
"language": {
"fields": "language"
} |
This can also be shortened, as the label can also serve as the field:
Set number of results
By default 10 results are returned for each fields. This can be changed by setting the size parameter. For example to retrieve the top 3 languages from the result set:
Code Block |
---|
|
"language": {
"size": 3
} |
Select multiple fields
To return the result counts for all values in multiple fields, simply list the fields:
Code Block |
---|
|
"multi": {
"fields": ["provider", "language"]
} |
Group by multiple fields
It's possible to add nested dimensions in an aggregation. The example below groups the result first by language and then within each language by provider:
...