Top hits: add support for options that were missing

Highlighting, explain, script fields, fielddata fields, and include
versions

Closes #1168

Author: gmarz

src/Nest/DSL/Aggregations/TopHitsAggregationDescriptor.cs

@@ -3,6 +3,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Linq.Expressions;
 using System.Text;
 
 namespace Nest
@@ -23,6 +24,22 @@ public interface ITopHitsAggregator : IMetricAggregator
 
 		[JsonProperty("_source")]
 		ISourceFilter Source { get; set; }
+
+		[JsonProperty("highlight")]
+		IHighlightRequest Highlight { get; set; }
+
+		[JsonProperty("explain")]
+		bool? Explain { get; set; }
+
+		[JsonProperty("script_fields")]
+		[JsonConverter(typeof(DictionaryKeysAreNotPropertyNamesJsonConverter))]
+		IDictionary<string, IScriptFilter> ScriptFields { get; set; }
+
+		[JsonProperty("fielddata_fields")]
+		IEnumerable<PropertyPathMarker> FieldDataFields { get; set; }
+
+		[JsonProperty("version")] 
+		bool? Version { get; set; }
 	}
 
 	public class TopHitsAggregator : MetricAggregator, ITopHitsAggregator
@@ -31,6 +48,11 @@ public class TopHitsAggregator : MetricAggregator, ITopHitsAggregator
 		public int? Size { get; set; }
 		public IList<KeyValuePair<PropertyPathMarker, ISort>> Sort { get; set; }
 		public ISourceFilter Source { get; set; }
+		public IHighlightRequest Highlight { get; set; }
+		public bool? Explain { get; set; }
+		public IDictionary<string, IScriptFilter> ScriptFields { get; set; }
+		public IEnumerable<PropertyPathMarker> FieldDataFields { get; set; }
+		public bool? Version { get; set; }
 	}
 
 	public class TopHitsAggregationDescriptor<T> 
@@ -47,6 +69,16 @@ public class TopHitsAggregationDescriptor<T>
 
 		ISourceFilter ITopHitsAggregator.Source { get; set; }
 
+		IHighlightRequest ITopHitsAggregator.Highlight { get; set; }
+
+		bool? ITopHitsAggregator.Explain { get; set; }
+
+		IDictionary<string, IScriptFilter> ITopHitsAggregator.ScriptFields { get; set; }
+
+		IEnumerable<PropertyPathMarker> ITopHitsAggregator.FieldDataFields { get; set; }
+
+		bool? ITopHitsAggregator.Version { get; set; }
+
 		public TopHitsAggregationDescriptor<T> From(int from)
 		{
 			this.Self.From = from;
@@ -87,5 +119,57 @@ public TopHitsAggregationDescriptor<T> Source(Func<SearchSourceDescriptor<T>, Se
 			this.Self.Source = sourceSelector(new SearchSourceDescriptor<T>());
 			return this;
 		}
+
+		public TopHitsAggregationDescriptor<T> Highlight(Func<HighlightDescriptor<T>, HighlightDescriptor<T>> highlightDescriptor)
+		{
+			highlightDescriptor.ThrowIfNull("highlightDescriptor");
+			this.Self.Highlight = highlightDescriptor(new HighlightDescriptor<T>());
+			return this;
+		}
+
+		public TopHitsAggregationDescriptor<T> Explain(bool explain = true)
+		{
+			this.Self.Explain = explain;
+			return this;
+		}
+
+		public TopHitsAggregationDescriptor<T> ScriptFields(
+			Func<FluentDictionary<string, Func<ScriptFilterDescriptor, ScriptFilterDescriptor>>,
+		 FluentDictionary<string, Func<ScriptFilterDescriptor, ScriptFilterDescriptor>>> scriptFields)
+		{
+			scriptFields.ThrowIfNull("scriptFields");
+			var scriptFieldDescriptors = scriptFields(new FluentDictionary<string, Func<ScriptFilterDescriptor, ScriptFilterDescriptor>>());
+			if (scriptFieldDescriptors == null || scriptFieldDescriptors.All(d => d.Value == null))
+			{
+				Self.ScriptFields = null;
+				return this;
+			}
+			Self.ScriptFields = new FluentDictionary<string, IScriptFilter>();
+			foreach (var d in scriptFieldDescriptors)
+			{
+				if (d.Value == null)
+					continue;
+				Self.ScriptFields.Add(d.Key, d.Value(new ScriptFilterDescriptor()));
+			}
+			return this;
+		}
+
+		public TopHitsAggregationDescriptor<T> FieldDataFields(params PropertyPathMarker[] fields)
+		{
+			this.Self.FieldDataFields = fields;
+			return this;
+		}
+
+		public TopHitsAggregationDescriptor<T> FieldDataFields(params Expression<Func<T, object>>[] objectPaths)
+		{
+			this.Self.FieldDataFields = objectPaths.Select(e => (PropertyPathMarker)e);
+			return this;
+		}
+
+		public TopHitsAggregationDescriptor<T> Version (bool version = true)
+		{
+			this.Self.Version = version;
+			return this;
+		}
 	}
 }

src/Nest/Domain/Aggregations/AggregationsHelper.cs

@@ -1,4 +1,5 @@
-using System.Collections.Generic;
+using System;
+using System.Collections.Generic;
 using System.Linq;
 
 namespace Nest
@@ -92,9 +93,15 @@ public PercentilesMetric PercentilesRank(string key)
 			return this.TryGet<PercentilesMetric>(key);
 		}
 
+		[Obsolete("Scheduled to be removed in 2.0.  Use TopHits() instead.")]
 		public TopHitsMetric TopHitsMetric(string key)
-		{
-			return this.TryGet<TopHitsMetric>(key);
+		{
+			return this.TopHits(key);
+		}
+
+		public TopHitsMetric TopHits(string key)
+		{
+			return this.TryGet<TopHitsMetric>(key);
 		}
 
         public FiltersBucket Filters(string key)

src/Nest/Domain/Aggregations/TopHitsMetric.cs

@@ -11,6 +11,8 @@ public class TopHitsMetric : IMetricAggregation
 	{
 		private IEnumerable<JObject> _hits;
 
+		internal JsonSerializer _defaultSerializer;
+
 		public TopHitsMetric()
 		{
 		}
@@ -20,22 +22,28 @@ internal TopHitsMetric(IEnumerable<JObject> hits)
 			_hits = hits;
 		}
 
+		internal TopHitsMetric(IEnumerable<JObject> hits, JsonSerializer serializer)
+		{
+			_hits = hits;
+			_defaultSerializer = serializer;
+		}
+
 		public long Total { get; set; }
 		public double? MaxScore { get; set; }
 
 		public IEnumerable<Hit<T>> Hits<T>(JsonSerializer serializer = null) where T : class
 		{
-			if (serializer != null)
-				return _hits.Select(h => h.ToObject<Hit<T>>(serializer));
+			var s = serializer ?? _defaultSerializer;
+
+			if (s != null)
+				return _hits.Select(h => h.ToObject<Hit<T>>(s));
+
 			return _hits.Select(h => h.ToObject<Hit<T>>());
 		}
 
 		public IEnumerable<T> Documents<T>(JsonSerializer serializer = null) where T : class
 		{
 			return this.Hits<T>(serializer).Select(h => h.Source);
 		}
-
-
 	}
-
 }

src/Nest/Resolvers/Converters/Aggregations/AggregationConverter.cs

@@ -79,7 +79,7 @@ private IAggregation GetHitsAggregation(JsonReader reader, JsonSerializer serial
 			var maxScore = o["max_score"].ToObject<double?>();
 			var hits = o["hits"].Children().OfType<JObject>().Select(s=>s);
 			reader.Read();
-			return new TopHitsMetric(hits) { Total = total, MaxScore = maxScore };
+			return new TopHitsMetric(hits, serializer) { Total = total, MaxScore = maxScore };
 		}
 
 		private IAggregation GetGeoBoundsMetricAggregation(JsonReader reader, JsonSerializer serializer)

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

@@ -173,6 +173,12 @@ public void TopHits()
 		{
 			var results = this.Client.Search<ElasticsearchProject>(s => s
 				.Size(0)
+				.Query(q => q
+					.Match(m => m
+						.OnField(p => p.Name)
+						.Query("elasticsearch")
+					)
+				)
 				.Aggregations(a => a
 					.Terms("top-countries", t => t
 						.Field(p => p.Country)
@@ -187,6 +193,26 @@ public void TopHits()
 									.Include(p => p.Name)
 								)
 								.Size(1)
+								.Explain(true)
+								.Version(true)
+								.Highlight(h => h
+									.PreTags("<em>")
+									.PostTags("</em>")
+									.OnFields(hf => hf
+										.OnField(p => p.Name)
+										.PreTags("<em>")
+										.PostTags("</em>")
+									)
+								)
+								.ScriptFields(sf => sf
+									.Add("locscriptfield", sff => sff
+										.Script("doc['loc'].value * multiplier")
+										.Params(sp => sp
+											.Add("multiplier", 2)
+										)
+									)
+								)
+								.FieldDataFields(p => p.Name, p => p.Country)
 							)
 						)
 					)
@@ -198,11 +224,17 @@ public void TopHits()
 			var topCountries = results.Aggs.Terms("top-countries").Items;
 			foreach(var topCountry in topCountries)
 			{
-				var topHits = topCountry.TopHitsMetric("top-country-hits");
+				var topHits = topCountry.TopHits("top-country-hits");
 				topHits.Should().NotBeNull();
 				topHits.Total.Should().BeGreaterThan(0);
 				var hits = topHits.Hits<ElasticsearchProject>();
 				hits.Should().NotBeEmpty().And.NotContain(h=> h.Id.IsNullOrEmpty() || h.Index.IsNullOrEmpty());
+				hits.All(h => h.Explanation != null).Should().BeTrue();
+				hits.All(h => !h.Version.IsNullOrEmpty()).Should().BeTrue();
+				hits.All(h => h.Highlights.Count() > 0).Should().BeTrue();
+				hits.All(h => h.Fields.FieldValues<int[]>("locscriptfield").HasAny()).Should().BeTrue();
+				hits.All(h => h.Fields.FieldValues<string[]>("name").HasAny()).Should().BeTrue();
+				hits.All(h => h.Fields.FieldValues<string[]>("country").HasAny()).Should().BeTrue();
 				topHits.Documents<ElasticsearchProject>().Should().NotBeEmpty();
 			}
 		}