Add geo-line aggregration (#5286)

* Add geo-line aggregation and initial test
* Make AggregationUsageTestBase generic
* Add documentation

Author: stevejgordon

docs/aggregations.asciidoc

@@ -46,6 +46,8 @@ The values are typically extracted from the fields of the document (using the fi
 
 * <<geo-centroid-aggregation-usage,Geo Centroid Aggregation Usage>>
 
+* <<geo-line-aggregation-usage,Geo Line Aggregation Usage>>
+
 * <<max-aggregation-usage,Max Aggregation Usage>>
 
 * <<median-absolute-deviation-aggregation-usage,Median Absolute Deviation Aggregation Usage>>
@@ -92,6 +94,8 @@ include::aggregations/metric/geo-bounds/geo-bounds-aggregation-usage.asciidoc[]
 
 include::aggregations/metric/geo-centroid/geo-centroid-aggregation-usage.asciidoc[]
 
+include::aggregations/metric/geo-line/geo-line-aggregation-usage.asciidoc[]
+
 include::aggregations/metric/max/max-aggregation-usage.asciidoc[]
 
 include::aggregations/metric/median-absolute-deviation/median-absolute-deviation-aggregation-usage.asciidoc[]

docs/aggregations/metric/geo-line/geo-line-aggregation-usage.asciidoc

@@ -0,0 +1,77 @@
+:ref_current: https://www.elastic.co/guide/en/elasticsearch/reference/7.11
+
+: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/7.x/src/Tests/Tests/Aggregations/Metric/GeoLine/GeoLineAggregationUsageTests.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!
+////
+
+[[geo-line-aggregation-usage]]
+=== Geo Line Aggregation Usage
+
+The geo_line aggregation aggregates all geo_point values within a bucket into a LineString ordered by the chosen sort field. 
+
+Be sure to read the Elasticsearch documentation on {ref_current}/search-aggregations-metrics-geo-line.html[Geo-Line Aggregation].
+
+==== Fluent DSL example
+
+[source,csharp]
+----
+a => a
+.GeoLine("line", d => d
+    .Point(p => p.LocationPoint)
+    .Sort(p => p.StartedOn)
+    .IncludeSort()
+    .Size(25))
+----
+
+==== Object Initializer syntax example
+
+[source,csharp]
+----
+new GeoLineAggregation("line", Field<Project>(f => f.LocationPoint), Field<Project>(f => f.StartedOn))
+{
+    IncludeSort = true,
+    Size = 25
+}
+----
+
+[source,javascript]
+.Example json output
+----
+{
+  "line": {
+    "geo_line": {
+      "point": {
+        "field": "locationPoint"
+      },
+      "sort": {
+        "field": "startedOn"
+      },
+      "include_sort": true,
+      "size": 25
+    }
+  }
+}
+----
+
+==== Handling Responses
+
+[source,csharp]
+----
+response.ShouldBeValid();
+var geoLine = response.Aggregations.GeoLine("line");
+geoLine.Should().NotBeNull();
+geoLine.Type.Should().Be("Feature");
+geoLine.Geometry.Type.Should().Be("linestring");
+geoLine.Geometry.Coordinates.Should().NotBeEmpty();
+geoLine.Properties.Complete.Should().BeFalse();
+geoLine.Properties.SortValues.Should().NotBeEmpty();
+----
+

src/Nest/Aggregations/AggregateDictionary.cs

@@ -94,6 +94,8 @@ public ScriptedMetricAggregate ScriptedMetric(string key)
 
 		public GeoBoundsAggregate GeoBounds(string key) => TryGet<GeoBoundsAggregate>(key);
 
+		public GeoLineAggregate GeoLine(string key) => TryGet<GeoLineAggregate>(key);
+
 		public PercentilesAggregate Percentiles(string key) => TryGet<PercentilesAggregate>(key);
 
 		public PercentilesAggregate PercentilesBucket(string key) => TryGet<PercentilesAggregate>(key);

src/Nest/Aggregations/AggregateDictionaryFormatter.cs

@@ -56,6 +56,9 @@ Dictionary<string, IAggregate> dictionary
 				case "geo_centroid":
 					ReadAggregate<GeoCentroidAggregate>(ref reader, formatterResolver, name, dictionary);
 					break;
+				case "geo_line":
+					ReadAggregate<GeoLineAggregate>(ref reader, formatterResolver, name, dictionary);
+					break;
 				default:
 					//still fall back to heuristics based parsed in case we do not know the key
 					ParseAggregate(ref reader, formatterResolver, name, dictionary);

src/Nest/Aggregations/AggregateFormatter.cs

@@ -38,6 +38,12 @@ internal class AggregateFormatter : IJsonFormatter<IAggregate>
 			{ Parser.BottomRight, 1 },
 		};
 
+		private static readonly AutomataDictionary GeoLineFields = new AutomataDictionary
+		{
+			{ Parser.Geometry, 0 },
+			{ Parser.Properties, 1 },
+		};
+
 		private static readonly byte[] KeysField = JsonWriter.GetEncodedPropertyNameWithoutQuotation(Parser.Keys);
 		private static readonly byte[] MetaField = JsonWriter.GetEncodedPropertyNameWithoutQuotation(Parser.Meta);
 		private static readonly byte[] MinLengthField = JsonWriter.GetEncodedPropertyNameWithoutQuotation(Parser.MinLength);
@@ -57,6 +63,7 @@ internal class AggregateFormatter : IJsonFormatter<IAggregate>
 			{ Parser.Fields, 10 },
 			{ Parser.Min, 11 },
 			{ Parser.Top, 12 },
+			{ Parser.Type, 13 }
 		};
 
 		private static readonly byte[] SumOtherDocCount = JsonWriter.GetEncodedPropertyNameWithoutQuotation(Parser.SumOtherDocCount);
@@ -174,6 +181,9 @@ private IAggregate ReadAggregate(ref JsonReader reader, IJsonFormatterResolver f
 					case 12:
 						aggregate = GetTopMetricsAggregate(ref reader, formatterResolver, meta);
 						break;
+					case 13:
+						aggregate = GetGeoLineAggregate(ref reader, formatterResolver, meta);
+						break;
 				}
 			}
 			else
@@ -273,7 +283,7 @@ private IAggregate GetBoxplotAggregate(ref JsonReader reader, IJsonFormatterReso
 			}
 
 			return boxplot;
-    }
+		}
 
 		private IAggregate GetTopMetricsAggregate(ref JsonReader reader, IJsonFormatterResolver formatterResolver, IReadOnlyDictionary<string, object> meta)
 		{
@@ -377,6 +387,45 @@ private IAggregate GetGeoBoundsAggregate(ref JsonReader reader, IJsonFormatterRe
 			return geoBoundsMetric;
 		}
 
+		private IAggregate GetGeoLineAggregate(ref JsonReader reader, IJsonFormatterResolver formatterResolver, IReadOnlyDictionary<string, object> meta)
+		{
+			var geoLine = new GeoLineAggregate { Meta = meta };
+
+			if (reader.GetCurrentJsonToken() == JsonToken.Null)
+			{
+				reader.ReadNext();
+				return geoLine;
+			}
+
+			var geometryFormatter = formatterResolver.GetFormatter<LineStringGeoShape>();
+			var propertiesFormatter = formatterResolver.GetFormatter<GeoLineProperties>();
+
+			geoLine.Type = reader.ReadString();
+			reader.ReadNext();
+
+			for (var i = 0; i < 2; i++)
+			{
+				var propertyName = reader.ReadPropertyNameSegmentRaw();
+				if (GeoLineFields.TryGetValue(propertyName, out var value))
+				{
+					switch (value)
+					{
+						case 0:
+							geoLine.Geometry = geometryFormatter.Deserialize(ref reader, formatterResolver);
+							reader.ReadNextBlock();
+							break;
+						case 1:
+							geoLine.Properties = propertiesFormatter.Deserialize(ref reader, formatterResolver);
+							break;
+					}
+				}
+				else
+					reader.ReadNextBlock();
+			}
+
+			return geoLine;
+		}
+
 		private IAggregate GetPercentilesAggregate(ref JsonReader reader, IReadOnlyDictionary<string, object> meta)
 		{
 			var metric = new PercentilesAggregate { Meta = meta };
@@ -944,17 +993,17 @@ private IBucket GetKeyedBucket(ref JsonReader reader, IJsonFormatterResolver for
 					case Parser.Score:
 						return GetSignificantTermsBucket(ref reader, formatterResolver, key, docCount);
 					case Parser.DocCountErrorUpperBound:
-					{
-						docCountErrorUpperBound = reader.ReadNullableLong();
-						token = reader.GetCurrentJsonToken();
-						if (token == JsonToken.ValueSeparator)
 						{
-							reader.ReadNext(); // ,
-							propertyName = reader.ReadPropertyName();
-							subAggregates = GetSubAggregates(ref reader, propertyName, formatterResolver);
+							docCountErrorUpperBound = reader.ReadNullableLong();
+							token = reader.GetCurrentJsonToken();
+							if (token == JsonToken.ValueSeparator)
+							{
+								reader.ReadNext(); // ,
+								propertyName = reader.ReadPropertyName();
+								subAggregates = GetSubAggregates(ref reader, propertyName, formatterResolver);
+							}
+							break;
 						}
-						break;
-					}
 					default:
 						subAggregates = GetSubAggregates(ref reader, propertyName, formatterResolver);
 						break;
@@ -1052,6 +1101,7 @@ private static class Parser
 			public const string Fields = "fields";
 			public const string From = "from";
 			public const string Top = "top";
+			public const string Type = "type";
 
 			public const string FromAsString = "from_as_string";
 			public const string Hits = "hits";
@@ -1078,6 +1128,9 @@ private static class Parser
 
 			public const string ValueAsString = "value_as_string";
 			public const string Values = "values";
+
+			public const string Geometry = "geometry";
+			public const string Properties = "properties";
 		}
 	}
 }

src/Nest/Aggregations/AggregationContainer.cs

@@ -162,6 +162,9 @@ public interface IAggregationContainer
 		[DataMember(Name = "geohash_grid")]
 		IGeoHashGridAggregation GeoHash { get; set; }
 
+		[DataMember(Name = "geo_line")]
+		IGeoLineAggregation GeoLine { get; set; }
+
 		[DataMember(Name = "geotile_grid")]
 		IGeoTileGridAggregation GeoTile { get; set; }
 
@@ -355,6 +358,8 @@ public class AggregationContainer : IAggregationContainer
 
 		public IGeoHashGridAggregation GeoHash { get; set; }
 
+		public IGeoLineAggregation GeoLine { get; set; }
+
 		public IGeoTileGridAggregation GeoTile { get; set; }
 
 		public IGlobalAggregation Global { get; set; }
@@ -520,6 +525,8 @@ public class AggregationContainerDescriptor<T> : DescriptorBase<AggregationConta
 
 		IGeoHashGridAggregation IAggregationContainer.GeoHash { get; set; }
 
+		IGeoLineAggregation IAggregationContainer.GeoLine { get; set; }
+
 		IGeoTileGridAggregation IAggregationContainer.GeoTile { get; set; }
 
 		IGlobalAggregation IAggregationContainer.Global { get; set; }
@@ -662,6 +669,10 @@ Func<GeoHashGridAggregationDescriptor<T>, IGeoHashGridAggregation> selector
 		) =>
 			_SetInnerAggregation(name, selector, (a, d) => a.GeoHash = d);
 
+		public AggregationContainerDescriptor<T> GeoLine(string name,
+			Func<GeoLineAggregationDescriptor<T>, IGeoLineAggregation> selector) =>
+			_SetInnerAggregation(name, selector, (a, d) => a.GeoLine = d);
+
 		public AggregationContainerDescriptor<T> GeoTile(string name,
 			Func<GeoTileGridAggregationDescriptor<T>, IGeoTileGridAggregation> selector
 		) =>

src/Nest/Aggregations/Metric/GeoLine/GeoLineAggregate.cs

@@ -0,0 +1,32 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using System.Collections.Generic;
+using System.Runtime.Serialization;
+
+namespace Nest
+{
+	[DataContract]
+	public class GeoLineAggregate : MetricAggregateBase
+	{
+		[DataMember(Name = "type")]
+		public string Type { get; set; }
+
+		[DataMember(Name = "geometry")]
+		public LineStringGeoShape Geometry { get; set; }
+
+		[DataMember(Name = "properties")]
+		public GeoLineProperties Properties { get; set; }
+	}
+
+	[DataContract]
+	public class GeoLineProperties
+	{
+		[DataMember(Name = "complete")]
+		public bool Complete { get; set; }
+
+		[DataMember(Name = "sort_values")]
+		public IEnumerable<double> SortValues { get; set; }
+	}
+}