Add additional sort options to Top Hits Aggregation (#2968)

* Add additional sort options to Top Hits Aggregation

Top Hits Aggregation fluent lambda syntax constrains sort options to field sorting, even though ITopHitsAggregation can accept any implementation of ISort. This commit deprecates the current fluent Sort implementation in favour of an implementation that allow multiple sort options besides field sorting, and assigns the resulting collection of sort options to IList<ISort>.

Update TopHitsAggregation usage test to call the new Sort method.

Fixes #2913

Author: russcam

docs/aggregations/metric/top-hits/top-hits-aggregation-usage.asciidoc

@@ -28,8 +28,18 @@ s => s
         .Aggregations(aa => aa
             .TopHits("top_state_hits", th => th
                 .Sort(srt => srt
-                    .Field(p => p.StartedOn)
-                    .Order(SortOrder.Descending)
+                    .Field(sf => sf
+                        .Field(p => p.StartedOn)
+                        .Order(SortOrder.Descending)
+                    )
+                    .Script(ss => ss
+                        .Type("number")
+                        .Script(sss => sss
+                            .Inline("Math.sin(34*(double)doc['numberOfCommits'].value)")
+                            .Lang("painless")
+                        )
+                        .Order(SortOrder.Descending)
+                    )
                 )
                 .Source(src => src
                     .Include(fs => fs
@@ -77,7 +87,13 @@ new SearchRequest<Project>
         {
             Sort = new List<ISort>
             {
-                new SortField { Field = Field<Project>(p => p.StartedOn), Order = SortOrder.Descending }
+                new SortField { Field = Field<Project>(p => p.StartedOn), Order = SortOrder.Descending },
+                new ScriptSort
+                {
+                    Type = "number",
+                    Script = new InlineScript("Math.sin(34*(double)doc['numberOfCommits'].value)") { Lang = "painless" },
+                    Order = SortOrder.Descending
+                },
             },
             Source = new SourceFilter
             {
@@ -122,6 +138,16 @@ new SearchRequest<Project>
                 "startedOn": {
                   "order": "desc"
                 }
+              },
+              {
+                "_script": {
+                  "type": "number",
+                  "script": {
+                    "lang": "painless",
+                    "inline": "Math.sin(34*(double)doc['numberOfCommits'].value)"
+                  },
+                  "order": "desc"
+                }
               }
             ],
             "_source": {

src/Nest/Aggregations/Metric/TopHits/TopHitsAggregation.cs

@@ -89,13 +89,17 @@ public class TopHitsAggregationDescriptor<T>
 
 		public TopHitsAggregationDescriptor<T> Size(int size) => Assign(a => a.Size = size);
 
+		[Obsolete("Use Sort(Func<SortDescriptor<T>, IPromise<IList<ISort>>>) that accepts multiple sort options")]
 		public TopHitsAggregationDescriptor<T> Sort(Func<SortFieldDescriptor<T>, IFieldSort> sortSelector) => Assign(a =>
 		{
 			a.Sort = a.Sort ?? new List<ISort>();
 			var sort = sortSelector?.Invoke(new SortFieldDescriptor<T>());
 			if (sort != null) a.Sort.Add(sort);
 		});
 
+		public TopHitsAggregationDescriptor<T> Sort(Func<SortDescriptor<T>, IPromise<IList<ISort>>> sortSelector) =>
+			Assign(a => a.Sort = sortSelector?.Invoke(new SortDescriptor<T>())?.Value);
+
 		public TopHitsAggregationDescriptor<T> Source(bool include = true) =>
 			Assign(a => a.Source = new SourceFilter { Disable = !include });
 

src/Tests/Aggregations/Metric/TopHits/TopHitsAggregationUsageTests.cs

@@ -40,6 +40,19 @@ public TopHitsAggregationUsageTests(ReadOnlyCluster i, EndpointUsage usage) : ba
 										{
 											order = "desc"
 										}
+									},
+									new
+									{
+										_script = new
+										{
+											type = "number",
+											script = new
+											{
+												lang = "painless",
+												inline = "Math.sin(34*(double)doc['numberOfCommits'].value)"
+											},
+											order = "desc"
+										}
 									}
 								},
 								_source = new
@@ -83,8 +96,18 @@ public TopHitsAggregationUsageTests(ReadOnlyCluster i, EndpointUsage usage) : ba
 					.Aggregations(aa => aa
 						.TopHits("top_state_hits", th => th
 							.Sort(srt => srt
-								.Field(p => p.StartedOn)
-								.Order(SortOrder.Descending)
+								.Field(sf => sf
+									.Field(p => p.StartedOn)
+									.Order(SortOrder.Descending)
+								)
+								.Script(ss => ss
+									.Type("number")
+									.Script(sss => sss
+										.Inline("Math.sin(34*(double)doc['numberOfCommits'].value)")
+										.Lang("painless")
+									)
+									.Order(SortOrder.Descending)
+								)
 							)
 							.Source(src => src
 								.Include(fs => fs
@@ -128,7 +151,13 @@ public TopHitsAggregationUsageTests(ReadOnlyCluster i, EndpointUsage usage) : ba
 					{
 						Sort = new List<ISort>
 						{
-							new SortField { Field = Field<Project>(p => p.StartedOn), Order = SortOrder.Descending }
+							new SortField { Field = Field<Project>(p => p.StartedOn), Order = SortOrder.Descending },
+							new ScriptSort
+							{
+								Type = "number",
+								Script = new InlineScript("Math.sin(34*(double)doc['numberOfCommits'].value)") { Lang = "painless" },
+								Order = SortOrder.Descending
+							},
 						},
 						Source = new SourceFilter
 						{