Add max_children to Nested Sort (#4596)

This commit adds max_children to nested sort.

Closes #4595

(cherry picked from commit 3110d3e)

Author: russcam

docs/search/request/sort-usage.asciidoc

@@ -244,6 +244,7 @@ s => s
             .Filter(ff => ff
                 .MatchAll()
             )
+            .MaxChildren(50)
         )
     )
 )
@@ -268,7 +269,8 @@ new SearchRequest<Project>
             Nested = new NestedSort
             {
                 Path = Field<Project>(p => p.Tags),
-                Filter = new MatchAllQuery()
+                Filter = new MatchAllQuery(),
+                MaxChildren = 50
             }
         }
     }
@@ -289,7 +291,8 @@ new SearchRequest<Project>
           "path": "tags",
           "filter": {
             "match_all": {}
-          }
+          },
+          "max_children": 50
         },
         "unmapped_type": "date"
       }

src/Nest/Search/Search/Sort/NestedSort.cs

@@ -5,42 +5,78 @@
 
 namespace Nest
 {
+	/// <summary>
+	/// Sort on a field inside one or more nested objects.
+	/// </summary>
 	[InterfaceDataContract]
 	[ReadAs(typeof(NestedSort))]
 	public interface INestedSort
 	{
+		/// <summary>
+		/// A filter that the inner objects inside the nested path should match with in order for its field values to be taken into account
+		/// by sorting. A common pattern is to repeat the query/filter inside the nested filter or query.
+		/// By default no nested filter is active.
+		/// </summary>
 		[DataMember(Name = "filter")]
 		QueryContainer Filter { get; set; }
 
+		/// <summary>
+		/// Same as top-level nested, but applies to another nested path within the current nested object.
+		/// </summary>
 		[DataMember(Name = "nested")]
 		INestedSort Nested { get; set; }
 
+		/// <summary>
+		/// Defines on which nested object to sort. The actual sort field must be a direct field inside this nested object.
+		/// When sorting by nested field, this field is mandatory.
+		/// </summary>
 		[DataMember(Name = "path")]
 		Field Path { get; set; }
+
+		/// <summary>
+		/// The maximum number of children to consider per root document when picking the sort value. Defaults to unlimited.
+		/// </summary>
+		[DataMember(Name = "max_children")]
+		int? MaxChildren { get; set; }
 	}
 
+	/// <inheritdoc />
 	public class NestedSort : INestedSort
 	{
+		/// <inheritdoc />
 		public QueryContainer Filter { get; set; }
+		/// <inheritdoc />
 		public INestedSort Nested { get; set; }
+		/// <inheritdoc />
 		public Field Path { get; set; }
+		/// <inheritdoc />
+		public int? MaxChildren { get; set; }
 	}
 
+	/// <inheritdoc cref="INestedSort"/>
 	public class NestedSortDescriptor<T>
 		: DescriptorBase<NestedSortDescriptor<T>, INestedSort>, INestedSort where T : class
 	{
 		QueryContainer INestedSort.Filter { get; set; }
 		INestedSort INestedSort.Nested { get; set; }
 		Field INestedSort.Path { get; set; }
+		int? INestedSort.MaxChildren { get; set; }
 
+		/// <inheritdoc cref="INestedSort.Path"/>
 		public NestedSortDescriptor<T> Path(Field path) => Assign(path, (a, v) => a.Path = v);
 
+		/// <inheritdoc cref="INestedSort.Path"/>
 		public NestedSortDescriptor<T> Path<TValue>(Expression<Func<T, TValue>> objectPath) => Assign(objectPath, (a, v) => a.Path = v);
 
+		/// <inheritdoc cref="INestedSort.Filter"/>
 		public NestedSortDescriptor<T> Filter(Func<QueryContainerDescriptor<T>, QueryContainer> filterSelector) =>
 			Assign(filterSelector, (a, v) => a.Filter = v?.Invoke(new QueryContainerDescriptor<T>()));
 
+		/// <inheritdoc cref="INestedSort.Nested"/>
 		public NestedSortDescriptor<T> Nested(Func<NestedSortDescriptor<T>, INestedSort> filterSelector) =>
 			Assign(filterSelector, (a, v) => a.Nested = v?.Invoke(new NestedSortDescriptor<T>()));
+
+		/// <inheritdoc cref="INestedSort.MaxChildren"/>
+		public NestedSortDescriptor<T> MaxChildren(int? maxChildren) => Assign(maxChildren, (a, v) => a.MaxChildren = v);
 	}
 }

tests/Tests/Search/Request/SortUsageTests.cs

@@ -250,7 +250,8 @@ public NestedSortUsageTests(ReadOnlyCluster cluster, EndpointUsage usage) : base
 									filter = new
 									{
 										match_all = new { }
-									}
+									},
+									max_children = 50
 								},
 								unmapped_type = "date"
 							}
@@ -272,6 +273,7 @@ public NestedSortUsageTests(ReadOnlyCluster cluster, EndpointUsage usage) : base
 						.Filter(ff => ff
 							.MatchAll()
 						)
+						.MaxChildren(50)
 					)
 				)
 			);
@@ -291,7 +293,8 @@ public NestedSortUsageTests(ReadOnlyCluster cluster, EndpointUsage usage) : base
 						Nested = new NestedSort
 						{
 							Path = Field<Project>(p => p.Tags),
-							Filter = new MatchAllQuery()
+							Filter = new MatchAllQuery(),
+							MaxChildren = 50
 						}
 					}
 				}