Add format to metric aggregations that support it (#4331)

This commit adds a Format property to metrics aggregations that support it.

Closes #4327

Author: russcam

src/Nest/Aggregations/Aggregation.cs

@@ -5,7 +5,7 @@
 namespace Nest
 {
 	/// <summary>
-	/// Represents an aggregation on the request
+	/// An aggregation on the request
 	/// </summary>
 	[InterfaceDataContract]
 	public interface IAggregation

src/Nest/Aggregations/Metric/Average/AverageAggregation.cs

@@ -4,9 +4,9 @@ namespace Nest
 {
 	[InterfaceDataContract]
 	[ReadAs(typeof(AverageAggregation))]
-	public interface IAverageAggregation : IMetricAggregation { }
+	public interface IAverageAggregation : IFormattableMetricAggregation { }
 
-	public class AverageAggregation : MetricAggregationBase, IAverageAggregation
+	public class AverageAggregation : FormattableMetricAggregationBase, IAverageAggregation
 	{
 		internal AverageAggregation() { }
 
@@ -16,7 +16,7 @@ public AverageAggregation(string name, Field field) : base(name, field) { }
 	}
 
 	public class AverageAggregationDescriptor<T>
-		: MetricAggregationDescriptorBase<AverageAggregationDescriptor<T>, IAverageAggregation, T>
+		: FormattableMetricAggregationDescriptorBase<AverageAggregationDescriptor<T>, IAverageAggregation, T>
 			, IAverageAggregation
 		where T : class { }
 }

src/Nest/Aggregations/Metric/ExtendedStats/ExtendedStatsAggregation.cs

@@ -5,13 +5,13 @@ namespace Nest
 {
 	[InterfaceDataContract]
 	[ReadAs(typeof(ExtendedStatsAggregation))]
-	public interface IExtendedStatsAggregation : IMetricAggregation
+	public interface IExtendedStatsAggregation : IFormattableMetricAggregation
 	{
 		[DataMember(Name ="sigma")]
 		double? Sigma { get; set; }
 	}
 
-	public class ExtendedStatsAggregation : MetricAggregationBase, IExtendedStatsAggregation
+	public class ExtendedStatsAggregation : FormattableMetricAggregationBase, IExtendedStatsAggregation
 	{
 		internal ExtendedStatsAggregation() { }
 
@@ -23,7 +23,7 @@ public ExtendedStatsAggregation(string name, Field field) : base(name, field) {
 	}
 
 	public class ExtendedStatsAggregationDescriptor<T>
-		: MetricAggregationDescriptorBase<ExtendedStatsAggregationDescriptor<T>, IExtendedStatsAggregation, T>
+		: FormattableMetricAggregationDescriptorBase<ExtendedStatsAggregationDescriptor<T>, IExtendedStatsAggregation, T>
 			, IExtendedStatsAggregation
 		where T : class
 	{

src/Nest/Aggregations/Metric/Max/MaxAggregation.cs

@@ -4,9 +4,9 @@ namespace Nest
 {
 	[InterfaceDataContract]
 	[ReadAs(typeof(MaxAggregation))]
-	public interface IMaxAggregation : IMetricAggregation { }
+	public interface IMaxAggregation : IFormattableMetricAggregation { }
 
-	public class MaxAggregation : MetricAggregationBase, IMaxAggregation
+	public class MaxAggregation : FormattableMetricAggregationBase, IMaxAggregation
 	{
 		internal MaxAggregation() { }
 
@@ -16,7 +16,7 @@ public MaxAggregation(string name, Field field) : base(name, field) { }
 	}
 
 	public class MaxAggregationDescriptor<T>
-		: MetricAggregationDescriptorBase<MaxAggregationDescriptor<T>, IMaxAggregation, T>
+		: FormattableMetricAggregationDescriptorBase<MaxAggregationDescriptor<T>, IMaxAggregation, T>
 			, IMaxAggregation
 		where T : class { }
 }

src/Nest/Aggregations/Metric/MedianAbsoluteDeviation/MedianAbsoluteDeviationAggregation.cs

@@ -16,7 +16,7 @@ namespace Nest
 	/// </summary>
 	[InterfaceDataContract]
 	[ReadAs(typeof(MedianAbsoluteDeviationAggregation))]
-	public interface IMedianAbsoluteDeviationAggregation : IMetricAggregation
+	public interface IMedianAbsoluteDeviationAggregation : IFormattableMetricAggregation
 	{
 		/// <summary>
 		/// TDigest algorithm component that controls memory usage and approximation error.
@@ -30,7 +30,7 @@ public interface IMedianAbsoluteDeviationAggregation : IMetricAggregation
 	}
 
 	/// <inheritdoc cref="IMedianAbsoluteDeviationAggregation"/>
-	public class MedianAbsoluteDeviationAggregation : MetricAggregationBase, IMedianAbsoluteDeviationAggregation
+	public class MedianAbsoluteDeviationAggregation : FormattableMetricAggregationBase, IMedianAbsoluteDeviationAggregation
 	{
 		internal MedianAbsoluteDeviationAggregation() { }
 
@@ -44,7 +44,7 @@ public MedianAbsoluteDeviationAggregation(string name, Field field) : base(name,
 
 	/// <inheritdoc cref="IMedianAbsoluteDeviationAggregation"/>
 	public class MedianAbsoluteDeviationAggregationDescriptor<T>
-		: MetricAggregationDescriptorBase<MedianAbsoluteDeviationAggregationDescriptor<T>, IMedianAbsoluteDeviationAggregation, T>
+		: FormattableMetricAggregationDescriptorBase<MedianAbsoluteDeviationAggregationDescriptor<T>, IMedianAbsoluteDeviationAggregation, T>
 			, IMedianAbsoluteDeviationAggregation
 		where T : class
 	{

src/Nest/Aggregations/Metric/MetricAggregation.cs

@@ -5,18 +5,44 @@
 
 namespace Nest
 {
+	/// <summary>
+	/// An aggregation that computes metrics based on values extracted in
+	/// one way or another from the documents that are being aggregated.
+	/// </summary>
 	public interface IMetricAggregation : IAggregation
 	{
+		/// <summary>
+		/// The field on which to aggregate
+		/// </summary>
 		[DataMember(Name ="field")]
 		Field Field { get; set; }
 
+		/// <summary>
+		/// The value to use when the aggregation finds a missing value in a document
+		/// </summary>
+		// TODO: This should be object in 8.x
 		[DataMember(Name ="missing")]
 		double? Missing { get; set; }
 
+		/// <summary>
+		/// The script to use for the aggregation
+		/// </summary>
 		[DataMember(Name ="script")]
 		IScript Script { get; set; }
 	}
 
+	/// <summary>
+	/// A metric aggregation that can accept a format to use for the output of the aggregation
+	/// </summary>
+	public interface IFormattableMetricAggregation : IMetricAggregation
+	{
+		/// <summary>
+		/// The format to use for the output of the aggregation
+		/// </summary>
+		[DataMember(Name = "format")]
+		string Format { get; set; }
+	}
+
 	public abstract class MetricAggregationBase : AggregationBase, IMetricAggregation
 	{
 		internal MetricAggregationBase() { }
@@ -28,6 +54,16 @@ internal MetricAggregationBase() { }
 		public virtual IScript Script { get; set; }
 	}
 
+	public abstract class FormattableMetricAggregationBase : MetricAggregationBase, IFormattableMetricAggregation
+	{
+		internal FormattableMetricAggregationBase() { }
+
+		protected FormattableMetricAggregationBase(string name, Field field) : base(name, field) { }
+
+		/// <inheritdoc />
+		public string Format { get; set; }
+	}
+
 	public abstract class MetricAggregationDescriptorBase<TMetricAggregation, TMetricAggregationInterface, T>
 		: DescriptorBase<TMetricAggregation, TMetricAggregationInterface>, IMetricAggregation
 		where TMetricAggregation : MetricAggregationDescriptorBase<TMetricAggregation, TMetricAggregationInterface, T>
@@ -45,18 +81,39 @@ public abstract class MetricAggregationDescriptorBase<TMetricAggregation, TMetri
 
 		IScript IMetricAggregation.Script { get; set; }
 
+		/// <inheritdoc cref="IMetricAggregation.Field"/>
 		public TMetricAggregation Field(Field field) => Assign(field, (a, v) => a.Field = v);
 
+		/// <inheritdoc cref="IMetricAggregation.Field"/>
 		public TMetricAggregation Field<TValue>(Expression<Func<T, TValue>> field) => Assign(field, (a, v) => a.Field = v);
 
+		/// <inheritdoc cref="IMetricAggregation.Script"/>
 		public virtual TMetricAggregation Script(string script) => Assign((InlineScript)script, (a, v) => a.Script = v);
 
+		/// <inheritdoc cref="IMetricAggregation.Script"/>
 		public virtual TMetricAggregation Script(Func<ScriptDescriptor, IScript> scriptSelector) =>
 			Assign(scriptSelector, (a, v) => a.Script = v?.Invoke(new ScriptDescriptor()));
 
+		/// <inheritdoc cref="IMetricAggregation.Missing"/>
 		public TMetricAggregation Missing(double? missing) => Assign(missing, (a, v) => a.Missing = v);
 
+		/// <inheritdoc cref="IAggregation.Meta"/>
 		public TMetricAggregation Meta(Func<FluentDictionary<string, object>, FluentDictionary<string, object>> selector) =>
 			Assign(selector, (a, v) => a.Meta = v?.Invoke(new FluentDictionary<string, object>()));
 	}
+
+	public abstract class FormattableMetricAggregationDescriptorBase<TFormattableMetricAggregation, TFormattableMetricAggregationInterface, T>
+		: MetricAggregationDescriptorBase<TFormattableMetricAggregation, TFormattableMetricAggregationInterface, T>, IFormattableMetricAggregation
+		where TFormattableMetricAggregation :
+		FormattableMetricAggregationDescriptorBase<TFormattableMetricAggregation, TFormattableMetricAggregationInterface, T>
+		, TFormattableMetricAggregationInterface, IFormattableMetricAggregation
+		where T : class
+		where TFormattableMetricAggregationInterface : class, IFormattableMetricAggregation
+	{
+		string IFormattableMetricAggregation.Format { get; set; }
+
+		/// <inheritdoc cref="IFormattableMetricAggregation.Format"/>
+		public TFormattableMetricAggregation Format(string format) =>
+			Assign(format, (a, v) => a.Format = v);
+	}
 }

src/Nest/Aggregations/Metric/Min/MinAggregation.cs

@@ -4,9 +4,9 @@ namespace Nest
 {
 	[InterfaceDataContract]
 	[ReadAs(typeof(MinAggregation))]
-	public interface IMinAggregation : IMetricAggregation { }
+	public interface IMinAggregation : IFormattableMetricAggregation { }
 
-	public class MinAggregation : MetricAggregationBase, IMinAggregation
+	public class MinAggregation : FormattableMetricAggregationBase, IMinAggregation
 	{
 		internal MinAggregation() { }
 
@@ -16,7 +16,7 @@ public MinAggregation(string name, Field field) : base(name, field) { }
 	}
 
 	public class MinAggregationDescriptor<T>
-		: MetricAggregationDescriptorBase<MinAggregationDescriptor<T>, IMinAggregation, T>
+		: FormattableMetricAggregationDescriptorBase<MinAggregationDescriptor<T>, IMinAggregation, T>
 			, IMinAggregation
 		where T : class { }
 }

src/Nest/Aggregations/Metric/PercentileRanks/PercentileRanksAggregation.cs

@@ -5,14 +5,14 @@
 namespace Nest
 {
 	[JsonFormatter(typeof(PercentileRanksAggregationFormatter))]
-	public interface IPercentileRanksAggregation : IMetricAggregation
+	public interface IPercentileRanksAggregation : IFormattableMetricAggregation
 	{
 		IPercentilesMethod Method { get; set; }
 		IEnumerable<double> Values { get; set; }
 		bool? Keyed { get; set; }
 	}
 
-	public class PercentileRanksAggregation : MetricAggregationBase, IPercentileRanksAggregation
+	public class PercentileRanksAggregation : FormattableMetricAggregationBase, IPercentileRanksAggregation
 	{
 		internal PercentileRanksAggregation() { }
 
@@ -26,7 +26,7 @@ public PercentileRanksAggregation(string name, Field field) : base(name, field)
 	}
 
 	public class PercentileRanksAggregationDescriptor<T>
-		: MetricAggregationDescriptorBase<PercentileRanksAggregationDescriptor<T>, IPercentileRanksAggregation, T>, IPercentileRanksAggregation
+		: FormattableMetricAggregationDescriptorBase<PercentileRanksAggregationDescriptor<T>, IPercentileRanksAggregation, T>, IPercentileRanksAggregation
 		where T : class
 	{
 		IPercentilesMethod IPercentileRanksAggregation.Method { get; set; }

src/Nest/Aggregations/Metric/PercentileRanks/PercentileRanksAggregationFormatter.cs

@@ -17,7 +17,8 @@ internal class PercentileRanksAggregationFormatter : IJsonFormatter<IPercentileR
 			{ "missing", 4 },
 			{ "meta", 5 },
 			{ "values", 6 },
-			{ "keyed", 7 }
+			{ "keyed", 7 },
+			{ "format", 8 }
 		};
 
 		public IPercentileRanksAggregation Deserialize(ref JsonReader reader, IJsonFormatterResolver formatterResolver)
@@ -67,6 +68,9 @@ public IPercentileRanksAggregation Deserialize(ref JsonReader reader, IJsonForma
 						case 7:
 							percentiles.Keyed = reader.ReadBoolean();
 							break;
+						case 8:
+							percentiles.Format = reader.ReadString();
+							break;
 					}
 				}
 			}
@@ -179,6 +183,16 @@ public void Serialize(ref JsonWriter writer, IPercentileRanksAggregation value,
 
 				writer.WritePropertyName("keyed");
 				writer.WriteBoolean(value.Keyed.Value);
+				propertyWritten = true;
+			}
+
+			if (!string.IsNullOrEmpty(value.Format))
+			{
+				if (propertyWritten)
+					writer.WriteValueSeparator();
+
+				writer.WritePropertyName("format");
+				writer.WriteString(value.Format);
 			}
 
 			writer.WriteEndObject();

src/Nest/Aggregations/Metric/Percentiles/PercentilesAggregation.cs

@@ -5,14 +5,14 @@
 namespace Nest
 {
 	[JsonFormatter(typeof(PercentilesAggregationFormatter))]
-	public interface IPercentilesAggregation : IMetricAggregation
+	public interface IPercentilesAggregation : IFormattableMetricAggregation
 	{
 		IPercentilesMethod Method { get; set; }
 		IEnumerable<double> Percents { get; set; }
 		bool? Keyed { get; set; }
 	}
 
-	public class PercentilesAggregation : MetricAggregationBase, IPercentilesAggregation
+	public class PercentilesAggregation : FormattableMetricAggregationBase, IPercentilesAggregation
 	{
 		internal PercentilesAggregation() { }
 
@@ -26,7 +26,7 @@ public PercentilesAggregation(string name, Field field) : base(name, field) { }
 	}
 
 	public class PercentilesAggregationDescriptor<T>
-		: MetricAggregationDescriptorBase<PercentilesAggregationDescriptor<T>, IPercentilesAggregation, T>
+		: FormattableMetricAggregationDescriptorBase<PercentilesAggregationDescriptor<T>, IPercentilesAggregation, T>
 			, IPercentilesAggregation
 		where T : class
 	{