Partial implementation of the top hits aggregation

TODO: Still need to implement a top hits response object and handle
deserialization in the AggregationConverter class.

Author: gmarz

src/Nest/DSL/Aggregations/AggregationDescriptor.cs

@@ -75,6 +75,9 @@ public interface IAggregationContainer
 		[JsonProperty("value_count")]
 		IValueCountAggregator ValueCount { get; set; }
 
+		[JsonProperty("top_hits")]
+		ITopHitsAggregator TopHits { get; set; }
+
 		[JsonProperty("aggs")]
 		[JsonConverter(typeof(DictionaryKeysAreNotPropertyNamesJsonConverter))]
 		IDictionary<string, IAggregationContainer> Aggregations { get; set; }
@@ -98,14 +101,14 @@ public class AggregationContainer : IAggregationContainer
 		private IRangeAggregator _range;
 		private ITermsAggregator _terms;
 		private ISignificantTermsAggregator _significantTerms;
+		private ITopHitsAggregator _topHits;
 		public IAverageAggregator Average { get; set; }
 		public IValueCountAggregator ValueCount { get; set; }
 		public IMaxAggregator Max { get; set; }
 		public IMinAggregator Min { get; set; }
 		public IStatsAggregator Stats { get; set; }
 		public ISumAggregator Sum { get; set; }
 		public IExtendedStatsAggregator ExtendedStats { get; set; }
-
 		public IDateHistogramAggregator DateHistogram
 		{
 			get { return _dateHistogram; }
@@ -196,6 +199,12 @@ public ISignificantTermsAggregator SignificantTerms
 			set { _significantTerms = value; }
 		}
 
+		public ITopHitsAggregator TopHits
+		{
+			get { return _topHits; }
+			set { _topHits = value; }
+		}
+
 		private void LiftAggregations(IBucketAggregator bucket)
 		{
 			if (bucket == null) return;
@@ -253,7 +262,9 @@ public class AggregationDescriptor<T> : IAggregationContainer
 		ISignificantTermsAggregator IAggregationContainer.SignificantTerms { get; set; }
 
 		ITermsAggregator IAggregationContainer.Terms { get; set; }
-		
+
+		ITopHitsAggregator IAggregationContainer.TopHits { get; set; }
+
 		public AggregationDescriptor<T> Average(string name, Func<AverageAggregationDescriptor<T>, AverageAggregationDescriptor<T>> selector)
 		{
 			return _SetInnerAggregation(name, selector, (a, d) => a.Average = d);
@@ -375,6 +386,12 @@ public AggregationDescriptor<T> ValueCount(string name,
 			return _SetInnerAggregation(name, selector, (a, d) => a.ValueCount = d);
 		}
 
+		public AggregationDescriptor<T> TopHits(string name,
+			Func<TopHitsAggregationDescriptor<T>, TopHitsAggregationDescriptor<T>> selector)
+		{
+			return _SetInnerAggregation(name, selector, (a, d) => a.TopHits = d);
+		}
+
 		private AggregationDescriptor<T> _SetInnerAggregation<TAggregation>(
 			string key,
 			Func<TAggregation, TAggregation> selector

src/Nest/DSL/Aggregations/TopHitsAggregationDescriptor.cs

@@ -0,0 +1,91 @@
+using Nest.Resolvers.Converters;
+using Newtonsoft.Json;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+
+namespace Nest
+{
+	[JsonObject(MemberSerialization = MemberSerialization.OptIn)]
+	[JsonConverter(typeof(ReadAsTypeConverter<TopHitsAggregator>))]
+	public interface ITopHitsAggregator : IMetricAggregator
+	{
+		[JsonProperty("from")]
+		int? From { get; set; }
+
+		[JsonProperty("size")]
+		int? Size { get; set; }
+
+		[JsonProperty("sort")]
+		[JsonConverter(typeof(SortCollectionConverter))]
+		IList<KeyValuePair<PropertyPathMarker, ISort>> Sort { get; set; }
+
+		[JsonProperty("_source")]
+		ISourceFilter Source { get; set; }
+	}
+
+	public class TopHitsAggregator : MetricAggregator, ITopHitsAggregator
+	{
+		public int? From { get; set; }
+		public int? Size { get; set; }
+		public IList<KeyValuePair<PropertyPathMarker, ISort>> Sort { get; set; }
+		public ISourceFilter Source { get; set; }
+	}
+
+	public class TopHitsAggregationDescriptor<T> 
+		: MetricAggregationBaseDescriptor<TopHitsAggregationDescriptor<T>, T>, ITopHitsAggregator
+		where T : class
+	{
+		ITopHitsAggregator Self { get { return this; } }
+
+		int? ITopHitsAggregator.From { get; set; }
+
+		int? ITopHitsAggregator.Size { get; set; }
+
+		IList<KeyValuePair<PropertyPathMarker, ISort>> ITopHitsAggregator.Sort { get; set; }
+
+		ISourceFilter ITopHitsAggregator.Source { get; set; }
+
+		public TopHitsAggregationDescriptor<T> From(int from)
+		{
+			this.Self.From = from;
+			return this;
+		}
+
+		public TopHitsAggregationDescriptor<T> Size(int size)
+		{
+			this.Self.Size = size;
+			return this;
+		}
+
+		public TopHitsAggregationDescriptor<T> Sort(Func<SortFieldDescriptor<T>, IFieldSort> sortSelector)
+		{
+			sortSelector.ThrowIfNull("sortSelector");
+
+			if (Self.Sort == null)
+				Self.Sort = new List<KeyValuePair<PropertyPathMarker, ISort>>();
+			
+			var descriptor = sortSelector(new SortFieldDescriptor<T>());
+			this.Self.Sort.Add(new KeyValuePair<PropertyPathMarker, ISort>(descriptor.Field, descriptor));
+			
+			return this;
+		}
+
+		public TopHitsAggregationDescriptor<T> Source(bool include = true)
+		{
+			if (!include)
+				this.Self.Source = new SourceFilter { Exclude = new PropertyPathMarker[] { "*" } };
+			else
+				this.Self.Source = null;
+
+			return this;
+		}
+
+		public TopHitsAggregationDescriptor<T> Source(Func<SearchSourceDescriptor<T>, SearchSourceDescriptor<T>> sourceSelector)
+		{
+			this.Self.Source = sourceSelector(new SearchSourceDescriptor<T>());
+			return this;
+		}
+	}
+}

src/Nest/Nest.csproj

@@ -207,6 +207,7 @@
     <Compile Include="Domain\Stats\PercolateStats.cs" />
     <Compile Include="Domain\Stats\PluginStats.cs" />
     <Compile Include="Domain\Stats\SegmentsStats.cs" />
+    <Compile Include="DSL\Aggregations\TopHitsAggregationDescriptor.cs" />
     <Compile Include="DSL\CatIndicesDescriptor.cs" />
     <Compile Include="DSL\CatShardsDescriptor.cs" />
     <Compile Include="DSL\CatThreadPoolDescriptor.cs" />

src/Tests/Nest.Tests.Integration/Aggregations/MetricAggregationTests.cs

@@ -119,5 +119,31 @@ public void ValueCount()
 			termBucket.Should().NotBeNull();
 			termBucket.Value.Should().HaveValue();
 		}
+
+		[Test]
+		public void TopHits()
+		{
+			var results = this.Client.Search<ElasticsearchProject>(s => s
+				.Size(0)
+				.Aggregations(a => a
+					.Terms("top-countries", t => t
+						.Field(p => p.Country)
+						.Size(3)
+						.Aggregations(aa => aa
+							.TopHits("top-country-hits", th => th
+								.Sort(sort => sort
+									.OnField(p => p.StartedOn)
+									.Order(SortOrder.Descending)
+								)
+								.Source(src => src
+									.Include(p => p.Name)
+								)
+								.Size(1)
+							)
+						)
+					)
+				)
+			);
+		}
 	}
 }