Item aggregation

Aggregations create the ability to get summarized views and statistics about the data. It allows you build data drill downs along the structured part of your items as well as visualizations over time or other data dimensions.

Specification

Request format

The request format is an url encoded JSON object of the following form:

{<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.
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. For date_time type facets the available intervals are: year, quarter, month, week, day, hour, minute, second.

Response format

 {
    "aggregations": {
        "<label>": {
            "<field_name>": {
                "values": [
                    {"key": "value1", "value": 11},
                    {"key": "value2", "value": 9},
                    .....
                ]
            }
        }
    }
}

or for numerically aggregated values:

{
    "aggregations": {
        "<label>": {
            "<field_name>": {
                "values": [
                    {"value": 11}
                ]
            }
        }
    }
}

or for sub aggregates:

{
    "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
                            }
                        ]
                    },
                    .....
                ]
            }
        }
    }
}

or for multiple labels:

{
    "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},
                    .....
                ]
            }
        }
    }
}

and for multiple fields within the same label:

 {
    "aggregations": {
        "<label>": {
            "<field_name1>": {
                "values": [
                    {"key": "value1", "value": 11},
                    {"key": "value2", "value": 9},
                    .....
                ]
            },
            "<field_name2>": {
                "values": [
                    {"key": "value3", "value": 7},
                    {"key": "value4", "value": 5},
                    .....
                ]
            }
        }
    }
}

Examples

Simple one dimensional value faceting over a single field

"language": {
    "fields": "language"
}

or even shorter as the label can also serve as the field:

 "language": {}

over multiples fields:

"multi": {
    "fields": ["provider", "language"]
}

setting the number of results you would like to get back

"language": {
    "size": 3
}

Adding another dimension to the aggregation: e.g. show the number of results for each language and provider

"language": {
    "aggregate": {"fields": "provider"}
}

Aggregations using a different method:

"$item_created_at": {
    "method": "histogram"
}

Aggregating the languages of items over time:

"$item_created_at": {
    "method": "histogram",
    "aggregation": {
       "fields": ["language"],
    }
}