|  | @@ -1,8 +1,8 @@
 | 
											
												
													
														|  |  [role="xpack"]
 |  |  [role="xpack"]
 | 
											
												
													
														|  |  [[search-aggregations-metrics-geo-line]]
 |  |  [[search-aggregations-metrics-geo-line]]
 | 
											
												
													
														|  | -=== Geo-Line Aggregation
 |  | 
 | 
											
												
													
														|  | 
 |  | +=== Geo-line aggregation
 | 
											
												
													
														|  |  ++++
 |  |  ++++
 | 
											
												
													
														|  | -<titleabbrev>Geo-Line</titleabbrev>
 |  | 
 | 
											
												
													
														|  | 
 |  | +<titleabbrev>Geo-line</titleabbrev>
 | 
											
												
													
														|  |  ++++
 |  |  ++++
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  |  The `geo_line` aggregation aggregates all `geo_point` values within a bucket into a `LineString` ordered
 |  |  The `geo_line` aggregation aggregates all `geo_point` values within a bucket into a `LineString` ordered
 | 
											
										
											
												
													
														|  | @@ -77,13 +77,12 @@ Which returns:
 | 
											
												
													
														|  |  The resulting https://tools.ietf.org/html/rfc7946#section-3.2[GeoJSON Feature] contains both a `LineString` geometry
 |  |  The resulting https://tools.ietf.org/html/rfc7946#section-3.2[GeoJSON Feature] contains both a `LineString` geometry
 | 
											
												
													
														|  |  for the path generated by the aggregation, as well as a map of `properties`.
 |  |  for the path generated by the aggregation, as well as a map of `properties`.
 | 
											
												
													
														|  |  The property `complete` informs of whether all documents matched were used to generate the geometry.
 |  |  The property `complete` informs of whether all documents matched were used to generate the geometry.
 | 
											
												
													
														|  | -The `size` option described below can be used to limit the number of documents included in the aggregation,
 |  | 
 | 
											
												
													
														|  | 
 |  | +The <<search-aggregations-metrics-geo-line-size,`size` option>> can be used to limit the number of documents included in the aggregation,
 | 
											
												
													
														|  |  leading to results  with `complete: false`.
 |  |  leading to results  with `complete: false`.
 | 
											
												
													
														|  | -Exactly which documents are dropped from results depends on whether the aggregation is based
 |  | 
 | 
											
												
													
														|  | -on `time_series` or not, and this is discussed in
 |  | 
 | 
											
												
													
														|  | -<<search-aggregations-metrics-geo-line-grouping-time-series-advantages,more detail below>>.
 |  | 
 | 
											
												
													
														|  | 
 |  | +Exactly which documents are dropped from results <<search-aggregations-metrics-geo-line-grouping-time-series-advantages,depends on whether the aggregation is based
 | 
											
												
													
														|  | 
 |  | +on `time_series` or not>>.
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  | -The above result could be displayed in a map user interface:
 |  | 
 | 
											
												
													
														|  | 
 |  | +This result could be displayed in a map user interface:
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  |  image:images/spatial/geo_line.png[Kibana map with museum tour of Amsterdam]
 |  |  image:images/spatial/geo_line.png[Kibana map with museum tour of Amsterdam]
 | 
											
												
													
														|  |  
 |  |  
 | 
											
										
											
												
													
														|  | @@ -132,18 +131,19 @@ feature properties.
 | 
											
												
													
														|  |  The line is sorted in ascending order by the sort key when set to "ASC", and in descending
 |  |  The line is sorted in ascending order by the sort key when set to "ASC", and in descending
 | 
											
												
													
														|  |  with "DESC".
 |  |  with "DESC".
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  | 
 |  | +[[search-aggregations-metrics-geo-line-size]]
 | 
											
												
													
														|  |  `size`::
 |  |  `size`::
 | 
											
												
													
														|  |  (Optional, integer, default: `10000`) The maximum length of the line represented in the aggregation.
 |  |  (Optional, integer, default: `10000`) The maximum length of the line represented in the aggregation.
 | 
											
												
													
														|  |  Valid sizes are between one and 10000.
 |  |  Valid sizes are between one and 10000.
 | 
											
												
													
														|  |  Within <<search-aggregations-metrics-geo-line-grouping-time-series,`time_series`>>
 |  |  Within <<search-aggregations-metrics-geo-line-grouping-time-series,`time_series`>>
 | 
											
												
													
														|  |  the aggregation uses line simplification to constrain the size, otherwise it uses truncation.
 |  |  the aggregation uses line simplification to constrain the size, otherwise it uses truncation.
 | 
											
												
													
														|  | -See <<search-aggregations-metrics-geo-line-grouping-time-series-advantages,below>>
 |  | 
 | 
											
												
													
														|  | 
 |  | +Refer to <<search-aggregations-metrics-geo-line-grouping-time-series-advantages>>
 | 
											
												
													
														|  |  for a discussion on the subtleties involved.
 |  |  for a discussion on the subtleties involved.
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  |  [[search-aggregations-metrics-geo-line-grouping]]
 |  |  [[search-aggregations-metrics-geo-line-grouping]]
 | 
											
												
													
														|  |  ==== Grouping
 |  |  ==== Grouping
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  | -The simple example above will produce a single track for all the data selected by the query. However, it is far more
 |  | 
 | 
											
												
													
														|  | 
 |  | +This simple example produces a single track for all the data selected by the query. However, it is far more
 | 
											
												
													
														|  |  common to need to group the data into multiple tracks. For example, grouping flight transponder measurements by
 |  |  common to need to group the data into multiple tracks. For example, grouping flight transponder measurements by
 | 
											
												
													
														|  |  flight call-sign before sorting each flight by timestamp and producing a separate track for each.
 |  |  flight call-sign before sorting each flight by timestamp and producing a separate track for each.
 | 
											
												
													
														|  |  
 |  |  
 | 
											
										
											
												
													
														|  | @@ -210,7 +210,7 @@ POST /tour/_bulk?refresh
 | 
											
												
													
														|  |  [[search-aggregations-metrics-geo-line-grouping-terms]]
 |  |  [[search-aggregations-metrics-geo-line-grouping-terms]]
 | 
											
												
													
														|  |  ==== Grouping with terms
 |  |  ==== Grouping with terms
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  | -Using the above data, for a non-time-series use case, the grouping can be done using a
 |  | 
 | 
											
												
													
														|  | 
 |  | +Using this data, for a non-time-series use case, the grouping can be done using a
 | 
											
												
													
														|  |  <<search-aggregations-bucket-terms-aggregation,terms aggregation>> based on city name.
 |  |  <<search-aggregations-bucket-terms-aggregation,terms aggregation>> based on city name.
 | 
											
												
													
														|  |  This would work whether or not we had defined the `tour` index as a time series index.
 |  |  This would work whether or not we had defined the `tour` index as a time series index.
 | 
											
												
													
														|  |  
 |  |  
 | 
											
										
											
												
													
														|  | @@ -294,17 +294,19 @@ Which returns:
 | 
											
												
													
														|  |  ----
 |  |  ----
 | 
											
												
													
														|  |  // TESTRESPONSE
 |  |  // TESTRESPONSE
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  | -The above results contain an array of buckets, where each bucket is a JSON object with the `key` showing the name
 |  | 
 | 
											
												
													
														|  | 
 |  | +These results contain an array of buckets, where each bucket is a JSON object with the `key` showing the name
 | 
											
												
													
														|  |  of the `city` field, and an inner aggregation result called `museum_tour` containing a
 |  |  of the `city` field, and an inner aggregation result called `museum_tour` containing a
 | 
											
												
													
														|  |  https://tools.ietf.org/html/rfc7946#section-3.2[GeoJSON Feature] describing the
 |  |  https://tools.ietf.org/html/rfc7946#section-3.2[GeoJSON Feature] describing the
 | 
											
												
													
														|  |  actual route between the various attractions in that city.
 |  |  actual route between the various attractions in that city.
 | 
											
												
													
														|  |  Each result also includes a `properties` object with a `complete` value which will be `false` if the geometry
 |  |  Each result also includes a `properties` object with a `complete` value which will be `false` if the geometry
 | 
											
												
													
														|  |  was truncated to the limits specified in the `size` parameter.
 |  |  was truncated to the limits specified in the `size` parameter.
 | 
											
												
													
														|  | -Note that when we use `time_series` in the example below, we will get the same results structured a little differently.
 |  | 
 | 
											
												
													
														|  | 
 |  | +Note that when we use `time_series` in the next example, we will get the same results structured a little differently.
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  |  [[search-aggregations-metrics-geo-line-grouping-time-series]]
 |  |  [[search-aggregations-metrics-geo-line-grouping-time-series]]
 | 
											
												
													
														|  |  ==== Grouping with time-series
 |  |  ==== Grouping with time-series
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  | 
 |  | +preview::[]
 | 
											
												
													
														|  | 
 |  | +
 | 
											
												
													
														|  |  Using the same data as before, we can also perform the grouping with a
 |  |  Using the same data as before, we can also perform the grouping with a
 | 
											
												
													
														|  |  <<search-aggregations-bucket-time-series-aggregation,`time_series` aggregation>>.
 |  |  <<search-aggregations-bucket-time-series-aggregation,`time_series` aggregation>>.
 | 
											
												
													
														|  |  This will group by TSID, which is defined as the combinations of all fields with `time_series_dimension: true`,
 |  |  This will group by TSID, which is defined as the combinations of all fields with `time_series_dimension: true`,
 | 
											
										
											
												
													
														|  | @@ -337,7 +339,7 @@ NOTE: The `geo_line` aggregation no longer requires the `sort` field when nested
 | 
											
												
													
														|  |  This is because the sort field is set to `@timestamp`, which all time-series indexes are pre-sorted by.
 |  |  This is because the sort field is set to `@timestamp`, which all time-series indexes are pre-sorted by.
 | 
											
												
													
														|  |  If you do set this parameter, and set it to something other than `@timestamp` you will get an error.
 |  |  If you do set this parameter, and set it to something other than `@timestamp` you will get an error.
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  | -The above query will result in:
 |  | 
 | 
											
												
													
														|  | 
 |  | +This query will result in:
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  |  [source,js]
 |  |  [source,js]
 | 
											
												
													
														|  |  ----
 |  |  ----
 | 
											
										
											
												
													
														|  | @@ -400,7 +402,7 @@ The above query will result in:
 | 
											
												
													
														|  |  ----
 |  |  ----
 | 
											
												
													
														|  |  // TESTRESPONSE
 |  |  // TESTRESPONSE
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  | -The above results are essentially the same as with the previous `terms` aggregation example, but structured differently.
 |  | 
 | 
											
												
													
														|  | 
 |  | +These results are essentially the same as with the previous `terms` aggregation example, but structured differently.
 | 
											
												
													
														|  |  Here we see the buckets returned as a map, where the key is an internal description of the TSID.
 |  |  Here we see the buckets returned as a map, where the key is an internal description of the TSID.
 | 
											
												
													
														|  |  This TSID is unique for each unique combination of fields with `time_series_dimension: true`.
 |  |  This TSID is unique for each unique combination of fields with `time_series_dimension: true`.
 | 
											
												
													
														|  |  Each bucket contains a `key` field which is also a map of all dimension values for the TSID, in this case only the city
 |  |  Each bucket contains a `key` field which is also a map of all dimension values for the TSID, in this case only the city
 | 
											
										
											
												
													
														|  | @@ -414,7 +416,7 @@ was simplified to the limits specified in the `size` parameter.
 | 
											
												
													
														|  |  [[search-aggregations-metrics-geo-line-grouping-time-series-advantages]]
 |  |  [[search-aggregations-metrics-geo-line-grouping-time-series-advantages]]
 | 
											
												
													
														|  |  ==== Why group with time-series?
 |  |  ==== Why group with time-series?
 | 
											
												
													
														|  |  
 |  |  
 | 
											
												
													
														|  | -When reviewing the above examples, you might think that there is little difference between using
 |  | 
 | 
											
												
													
														|  | 
 |  | +When reviewing these examples, you might think that there is little difference between using
 | 
											
												
													
														|  |  <<search-aggregations-bucket-terms-aggregation,`terms`>> or
 |  |  <<search-aggregations-bucket-terms-aggregation,`terms`>> or
 | 
											
												
													
														|  |  <<search-aggregations-bucket-time-series-aggregation,`time_series`>>
 |  |  <<search-aggregations-bucket-time-series-aggregation,`time_series`>>
 | 
											
												
													
														|  |  to group the geo-lines. However, there are some important differences in behaviour between the two cases.
 |  |  to group the geo-lines. However, there are some important differences in behaviour between the two cases.
 |