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.

Field 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_hits 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 to return the buckets by
relevancy order of the most relevant document in a bucket.

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. Unfortunately the top_hits aggregator
can’t be used in the order option of the terms aggregator yet.

If the top_hits aggregator is wrapped in a nested or reverse_nested aggregator then nested hits are being returned.
Nested hits are in a sense hidden mini documents that are part of regular document where in the mapping a nested field type
has been configured. The top_hits aggregator has the ability to un-hide these documents if it is wrapped in a nested
or reverse_nested aggregator. Read more about nested in the nested type mapping.

If nested type has been configured a single document is actually indexed as multiple Lucene documents and they share
the same id. In order to determine the identity of a nested hit there is more needed than just the id, so that is why
nested hits also include their nested identity. The nested identity is kept under the _nested field in the search hit
and includes the array field and the offset in the array field the nested hit belongs to. The offset is zero based.

Let’s see how it works with a real sample. Considering the following mapping:

If _source is requested then just the part of the source of the nested object is returned, not the entire source of the document.
Also stored fields on the nested inner object level are accessible via top_hits aggregator residing in a nested or reverse_nested aggregator.

Only nested hits will have a _nested field in the hit, non nested (regular) hits will not have a _nested field.

The information in _nested can also be used to parse the original source somewhere else if _source isn’t enabled.

If there are multiple levels of nested object types defined in mappings then the _nested information can also be hierarchical
in order to express the identity of nested hits that are two layers deep or more.

In the example below a nested hit resides in the first slot of the field nested_grand_child_field which then resides in
the second slow of the nested_child_field field: