Implement Boxplot aggregation

Relates: elastic/elasticsearch#51948

This commit implements the boxplot aggregation.
Integration tests run against XPackCluster because
it requires a license to use.

Author: russcam

docs/aggregations.asciidoc

@@ -36,6 +36,8 @@ The values are typically extracted from the fields of the document (using the fi
 
 * <<average-aggregation-usage,Average Aggregation Usage>>
 
+* <<boxplot-aggregation-usage,Boxplot Aggregation Usage>>
+
 * <<cardinality-aggregation-usage,Cardinality Aggregation Usage>>
 
 * <<extended-stats-aggregation-usage,Extended Stats Aggregation Usage>>
@@ -74,6 +76,8 @@ See the Elasticsearch documentation on {ref_current}/search-aggregations-metrics
 
 include::aggregations/metric/average/average-aggregation-usage.asciidoc[]
 
+include::aggregations/metric/boxplot/boxplot-aggregation-usage.asciidoc[]
+
 include::aggregations/metric/cardinality/cardinality-aggregation-usage.asciidoc[]
 
 include::aggregations/metric/extended-stats/extended-stats-aggregation-usage.asciidoc[]

docs/aggregations/metric/boxplot/boxplot-aggregation-usage.asciidoc

@@ -0,0 +1,88 @@
+:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/master
+
+:github: https://github.com/elastic/elasticsearch-net
+
+:nuget: https://www.nuget.org/packages
+
+////
+IMPORTANT NOTE
+==============
+This file has been generated from https://github.com/elastic/elasticsearch-net/tree/master/src/Tests/Tests/Aggregations/Metric/Boxplot/BoxplotAggregationUsageTests.cs. 
+If you wish to submit a PR for any spelling mistakes, typos or grammatical errors for this file,
+please modify the original csharp file found at the link and submit the PR with that change. Thanks!
+////
+
+[[boxplot-aggregation-usage]]
+=== Boxplot Aggregation Usage
+
+A boxplot metrics aggregation that computes boxplot of numeric values extracted from the aggregated documents.
+These values can be generated by a provided script or extracted from specific numeric or histogram fields in the documents.
+
+boxplot aggregation returns essential information for making a box plot: minimum, maximum median, first quartile (25th percentile)
+and third quartile (75th percentile) values.
+
+Be sure to read the Elasticsearch documentation on {ref_current}/search-aggregations-metrics-boxplot-aggregation.html[Boxplot Aggregation]
+
+==== Fluent DSL example
+
+[source,csharp]
+----
+a => a
+.Boxplot("boxplot_commits", plot => plot
+    .Meta(m => m
+        .Add("foo", "bar")
+    )
+    .Field(p => p.NumberOfCommits)
+    .Missing(10)
+    .Compression(100)
+)
+----
+
+==== Object Initializer syntax example
+
+[source,csharp]
+----
+new BoxplotAggregation("boxplot_commits", Field<Project>(p => p.NumberOfCommits))
+{
+    Meta = new Dictionary<string, object>
+    {
+        { "foo", "bar" }
+    },
+    Missing = 10,
+    Compression = 100
+}
+----
+
+[source,javascript]
+.Example json output
+----
+{
+  "boxplot_commits": {
+    "meta": {
+      "foo": "bar"
+    },
+    "boxplot": {
+      "field": "numberOfCommits",
+      "missing": 10.0,
+      "compression": 100.0
+    }
+  }
+}
+----
+
+==== Handling Responses
+
+[source,csharp]
+----
+response.ShouldBeValid();
+var boxplot = response.Aggregations.Boxplot("boxplot_commits");
+boxplot.Should().NotBeNull();
+boxplot.Min.Should().BeGreaterOrEqualTo(0);
+boxplot.Max.Should().BeGreaterOrEqualTo(0);
+boxplot.Q1.Should().BeGreaterOrEqualTo(0);
+boxplot.Q2.Should().BeGreaterOrEqualTo(0);
+boxplot.Q3.Should().BeGreaterOrEqualTo(0);
+boxplot.Meta.Should().NotBeNull().And.HaveCount(1);
+boxplot.Meta["foo"].Should().Be("bar");
+----
+

src/Nest/Aggregations/AggregateDictionary.cs

@@ -236,6 +236,8 @@ public CompositeBucketAggregate Composite(string key)
 
 		public ValueAggregate MedianAbsoluteDeviation(string key) => TryGet<ValueAggregate>(key);
 
+		public BoxplotAggregate Boxplot(string key) => TryGet<BoxplotAggregate>(key);
+
 		private TAggregate TryGet<TAggregate>(string key) where TAggregate : class, IAggregate =>
 			BackingDictionary.TryGetValue(key, out var agg) ? agg as TAggregate : null;
 

src/Nest/Aggregations/AggregateFormatter.cs

@@ -51,6 +51,7 @@ internal class AggregateFormatter : IJsonFormatter<IAggregate>
 			{ Parser.Hits, 8 },
 			{ Parser.Location, 9 },
 			{ Parser.Fields, 10 },
+			{ Parser.Min, 11 }
 		};
 
 		private static readonly byte[] SumOtherDocCount = JsonWriter.GetEncodedPropertyNameWithoutQuotation(Parser.SumOtherDocCount);
@@ -151,6 +152,9 @@ private IAggregate ReadAggregate(ref JsonReader reader, IJsonFormatterResolver f
 					case 10:
 						aggregate = GetMatrixStatsAggregate(ref reader, formatterResolver, meta);
 						break;
+					case 11:
+						aggregate = GetBoxplotAggregate(ref reader, formatterResolver, meta);
+						break;
 				}
 			}
 			else
@@ -212,6 +216,32 @@ private IAggregate GetMatrixStatsAggregate(ref JsonReader reader, IJsonFormatter
 			return matrixStats;
 		}
 
+		private IAggregate GetBoxplotAggregate(ref JsonReader reader, IJsonFormatterResolver formatterResolver, IReadOnlyDictionary<string, object> meta)
+		{
+			var boxplot = new BoxplotAggregate
+			{
+				Min = reader.ReadDouble(),
+				Meta = meta
+			};
+			reader.ReadNext(); // ,
+			reader.ReadNext(); // "max"
+			reader.ReadNext(); // :
+			boxplot.Max = reader.ReadDouble();
+			reader.ReadNext(); // ,
+			reader.ReadNext(); // "q1"
+			reader.ReadNext(); // :
+			boxplot.Q1 = reader.ReadDouble();
+			reader.ReadNext(); // ,
+			reader.ReadNext(); // "q2"
+			reader.ReadNext(); // :
+			boxplot.Q2 = reader.ReadDouble();
+			reader.ReadNext(); // ,
+			reader.ReadNext(); // "q3"
+			reader.ReadNext(); // :
+			boxplot.Q3 = reader.ReadDouble();
+			return boxplot;
+		}
+
 		private IAggregate GetTopHitsAggregate(ref JsonReader reader, IJsonFormatterResolver formatterResolver, IReadOnlyDictionary<string, object> meta)
 		{
 			var count = 0;
@@ -982,6 +1012,7 @@ private static class Parser
 			public const string Location = "location";
 			public const string MaxScore = "max_score";
 			public const string Meta = "meta";
+			public const string Min = "min";
 			public const string MinLength = "min_length";
 
 			public const string Score = "score";

src/Nest/Aggregations/AggregationContainer.cs

@@ -92,6 +92,9 @@ public interface IAggregationContainer
 		[DataMember(Name = "avg_bucket")]
 		IAverageBucketAggregation AverageBucket { get; set; }
 
+		[DataMember(Name = "boxplot")]
+		IBoxplotAggregation Boxplot { get; set; }
+
 		[DataMember(Name = "bucket_script")]
 		IBucketScriptAggregation BucketScript { get; set; }
 
@@ -274,6 +277,9 @@ public class AggregationContainer : IAggregationContainer
 
 		public IAverageBucketAggregation AverageBucket { get; set; }
 
+		/// <inheritdoc cref="IBoxplotAggregation"/>
+		public IBoxplotAggregation Boxplot { get; set; }
+
 		public IBucketScriptAggregation BucketScript { get; set; }
 
 		public IBucketSelectorAggregation BucketSelector { get; set; }
@@ -422,6 +428,8 @@ public class AggregationContainerDescriptor<T> : DescriptorBase<AggregationConta
 
 		IAverageBucketAggregation IAggregationContainer.AverageBucket { get; set; }
 
+		IBoxplotAggregation IAggregationContainer.Boxplot { get; set; }
+
 		IBucketScriptAggregation IAggregationContainer.BucketScript { get; set; }
 
 		IBucketSelectorAggregation IAggregationContainer.BucketSelector { get; set; }
@@ -831,6 +839,12 @@ Func<StringStatsAggregationDescriptor<T>, IStringStatsAggregation> selector
 		) =>
 			_SetInnerAggregation(name, selector, (a, d) => a.StringStats = d);
 
+		/// <inheritdoc cref="IBoxplotAggregation"/>
+		public AggregationContainerDescriptor<T> Boxplot(string name,
+			Func<BoxplotAggregationDescriptor<T>, IBoxplotAggregation> selector
+		) =>
+			_SetInnerAggregation(name, selector, (a, d) => a.Boxplot = d);
+
 		/// <summary>
 		/// Fluent methods do not assign to properties on `this` directly but on IAggregationContainers inside
 		/// `this.Aggregations[string, IContainer]

src/Nest/Aggregations/Metric/Boxplot/BoxplotAggregate.cs

@@ -0,0 +1,14 @@
+namespace Nest {
+	public class BoxplotAggregate : MetricAggregateBase
+	{
+		public double Min { get; set; }
+
+		public double Max { get; set; }
+
+		public double Q1 { get; set; }
+
+		public double Q2 { get; set; }
+
+		public double Q3 { get; set; }
+	}
+}

src/Nest/Aggregations/Metric/Boxplot/BoxplotAggregation.cs

@@ -0,0 +1,51 @@
+using System.Runtime.Serialization;
+using Elasticsearch.Net.Utf8Json;
+
+namespace Nest
+{
+	/// <summary>
+	/// A metrics aggregation that computes boxplot of numeric values extracted from the aggregated documents.
+	/// These values can be generated by a provided script or extracted from specific numeric or histogram fields in the documents.
+	/// <para />
+	/// Available in Elasticsearch 7.7.0+ with at least basic license level
+	/// </summary>
+	[InterfaceDataContract]
+	[ReadAs(typeof(BoxplotAggregation))]
+	public interface IBoxplotAggregation : IMetricAggregation
+	{
+		/// <summary>
+		/// Balances memory utilization with estimation accuracy.
+		/// Increasing compression, increases the accuracy of percentiles at the cost
+		/// of more memory. Larger compression values also make the algorithm slower since the underlying tree data structure grows in size,
+		/// resulting in more expensive operations.
+		/// </summary>
+		[DataMember(Name = "compression")]
+		double? Compression { get; set; }
+	}
+
+	/// <inheritdoc cref="IBoxplotAggregation"/>
+	public class BoxplotAggregation : MetricAggregationBase, IBoxplotAggregation
+	{
+		internal BoxplotAggregation() { }
+
+		public BoxplotAggregation(string name, Field field) : base(name, field) { }
+
+		internal override void WrapInContainer(AggregationContainer c) => c.Boxplot = this;
+
+		/// <inheritdoc />
+		public double? Compression { get; set; }
+	}
+
+	/// <inheritdoc cref="IBoxplotAggregation"/>
+	public class BoxplotAggregationDescriptor<T>
+		: MetricAggregationDescriptorBase<BoxplotAggregationDescriptor<T>, IBoxplotAggregation, T>
+			, IBoxplotAggregation
+		where T : class
+	{
+		double? IBoxplotAggregation.Compression { get; set; }
+
+		/// <inheritdoc cref="IBoxplotAggregation.Compression"/>
+		public BoxplotAggregationDescriptor<T> Compression(double? compression) =>
+			Assign(compression, (a, v) => a.Compression = v);
+	}
+}

src/Nest/Aggregations/Visitor/AggregationVisitor.cs

@@ -139,6 +139,8 @@ public interface IAggregationVisitor
 		void Visit(IMovingFunctionAggregation aggregation);
 
 		void Visit(IStringStatsAggregation aggregation);
+
+		void Visit(IBoxplotAggregation aggregation);
 	}
 
 	public class AggregationVisitor : IAggregationVisitor
@@ -263,6 +265,8 @@ public virtual void Visit(IMovingFunctionAggregation aggregation) { }
 
 		public virtual void Visit(IStringStatsAggregation aggregation) { }
 
+		public virtual void Visit(IBoxplotAggregation aggregation) { }
+
 		public virtual void Visit(IAggregation aggregation) { }
 
 		public virtual void Visit(IAggregationContainer aggregationContainer) { }

src/Nest/Aggregations/Visitor/AggregationWalker.cs

@@ -38,6 +38,7 @@ public void Walk(IAggregationContainer aggregation, IAggregationVisitor visitor)
 			visitor.Visit(aggregation);
 			AcceptAggregation(aggregation.Average, visitor, (v, d) => v.Visit(d));
 			AcceptAggregation(aggregation.AverageBucket, visitor, (v, d) => v.Visit(d));
+			AcceptAggregation(aggregation.Boxplot, visitor, (v, d) => v.Visit(d));
 			AcceptAggregation(aggregation.BucketScript, visitor, (v, d) => v.Visit(d));
 			AcceptAggregation(aggregation.BucketSort, visitor, (v, d) => v.Visit(d));
 			AcceptAggregation(aggregation.BucketSelector, visitor, (v, d) => v.Visit(d));

tests/Tests/Aggregations/AggregationUsageTestBase.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Threading.Tasks;
+using Elastic.Managed.Ephemeral;
 using Elastic.Xunit.XunitPlumbing;
 using Elasticsearch.Net;
 using Nest;
@@ -13,10 +14,15 @@
 
 namespace Tests.Aggregations
 {
-	public abstract class AggregationUsageTestBase
-		: ApiIntegrationTestBase<ReadOnlyCluster, ISearchResponse<Project>, ISearchRequest, SearchDescriptor<Project>, SearchRequest<Project>>
-	{
+	public abstract class AggregationUsageTestBase : AggregationUsageTestBase<ReadOnlyCluster> {
 		protected AggregationUsageTestBase(ReadOnlyCluster cluster, EndpointUsage usage) : base(cluster, usage) { }
+	}
+
+	public abstract class AggregationUsageTestBase<TCluster>
+		: ApiIntegrationTestBase<TCluster, ISearchResponse<Project>, ISearchRequest, SearchDescriptor<Project>, SearchRequest<Project>>
+		where TCluster : IEphemeralCluster<EphemeralClusterConfiguration>, INestTestCluster, new()
+	{
+		protected AggregationUsageTestBase(TCluster cluster, EndpointUsage usage) : base(cluster, usage) { }
 
 		protected virtual Nest.Indices AgainstIndex { get; } = Index<Project>();