WARNING: Version 1.3 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
Top hits Aggregation
editTop hits Aggregation
editAdded in 1.3.0.
A top_hits metric aggregator keeps track of the most relevant document being aggregated. This aggregator is intended
to be used as a sub aggregator, so that the top matching documents can be aggregated per bucket.
The top_hits aggregator can effectively be used to group result sets by certain fields via a bucket aggregator.
One or more bucket aggregators determines by which properties a result set get sliced into.
Options
edit-
from- The offset from the first result you want to fetch. -
size- The maximum number of top matching hits to return per bucket. By default the top three matching hits are returned. -
sort- How the top matching hits should be sorted. By default the hits are sorted by the score of the main query.
Supported per hit features
editThe top_hits aggregation returns regular search hits, because of this many per hit features can be supported:
Example
editIn the following example we group the questions by tag and per tag we show the last active question. For each question only the title field is being included in the source.
{
"aggs": {
"top-tags": {
"terms": {
"field": "tags",
"size": 3
},
"aggs": {
"top_tag_hits": {
"top_hits": {
"sort": [
{
"last_activity_date": {
"order": "desc"
}
}
],
"_source": {
"include": [
"title"
]
},
"size" : 1
}
}
}
}
}
}
Possible response snippet:
"aggregations": {
"top-tags": {
"buckets": [
{
"key": "windows-7",
"doc_count": 25365,
"top_tags_hits": {
"hits": {
"total": 25365,
"max_score": 1,
"hits": [
{
"_index": "stack",
"_type": "question",
"_id": "602679",
"_score": 1,
"_source": {
"title": "Windows port opening"
},
"sort": [
1370143231177
]
}
]
}
}
},
{
"key": "linux",
"doc_count": 18342,
"top_tags_hits": {
"hits": {
"total": 18342,
"max_score": 1,
"hits": [
{
"_index": "stack",
"_type": "question",
"_id": "602672",
"_score": 1,
"_source": {
"title": "Ubuntu RFID Screensaver lock-unlock"
},
"sort": [
1370143379747
]
}
]
}
}
},
{
"key": "windows",
"doc_count": 18119,
"top_tags_hits": {
"hits": {
"total": 18119,
"max_score": 1,
"hits": [
{
"_index": "stack",
"_type": "question",
"_id": "602678",
"_score": 1,
"_source": {
"title": "If I change my computers date / time, what could be affected?"
},
"sort": [
1370142868283
]
}
]
}
}
}
]
}
}
Field collapse example
editField collapsing or result grouping is a feature that logically groups a result set into groups and per group returns
top documents. The ordering of the groups is determined by the relevancy of the first document in a group. In
Elasticsearch this can be implemented via a bucket aggregator that wraps a top_hits aggregator as sub-aggregator.
In the example below we search across crawled webpages. For each webpage we store the body and the domain the webpage
belong to. By defining a terms aggregator on the domain field we group the result set of webpages by domain. The
top_docs aggregator is then defined as sub-aggregator, so that the top matching hits are collected per bucket.
Also a max aggregator is defined which is used by the terms aggregator’s order feature the return the buckets by
relevancy order of the most relevant document in a bucket.
{
"query": {
"match": {
"body": "elections"
}
},
"aggs": {
"top-sites": {
"terms": {
"field": "domain",
"order": {
"top_hit": "desc"
}
},
"aggs": {
"top_tags_hits": {
"top_hits": {}
},
"top_hit" : {
"max": {
"script": "_score"
}
}
}
}
}
}
At the moment the max (or min) aggregator is needed to make sure the buckets from the terms aggregator are
ordered according to the score of the most relevant webpage per domain. The top_hits aggregator isn’t a metric aggregator
and therefore can’t be used in the order option of the terms aggregator.