|
|
@@ -1,8 +1,8 @@
|
|
|
[role="xpack"]
|
|
|
[[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
|
|
|
@@ -77,13 +77,12 @@ Which returns:
|
|
|
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`.
|
|
|
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`.
|
|
|
-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]
|
|
|
|
|
|
@@ -132,18 +131,19 @@ feature properties.
|
|
|
The line is sorted in ascending order by the sort key when set to "ASC", and in descending
|
|
|
with "DESC".
|
|
|
|
|
|
+[[search-aggregations-metrics-geo-line-size]]
|
|
|
`size`::
|
|
|
(Optional, integer, default: `10000`) The maximum length of the line represented in the aggregation.
|
|
|
Valid sizes are between one and 10000.
|
|
|
Within <<search-aggregations-metrics-geo-line-grouping-time-series,`time_series`>>
|
|
|
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.
|
|
|
|
|
|
[[search-aggregations-metrics-geo-line-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
|
|
|
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]]
|
|
|
==== 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.
|
|
|
This would work whether or not we had defined the `tour` index as a time series index.
|
|
|
|
|
|
@@ -294,17 +294,19 @@ Which returns:
|
|
|
----
|
|
|
// 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
|
|
|
https://tools.ietf.org/html/rfc7946#section-3.2[GeoJSON Feature] describing the
|
|
|
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
|
|
|
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]]
|
|
|
==== Grouping with time-series
|
|
|
|
|
|
+preview::[]
|
|
|
+
|
|
|
Using the same data as before, we can also perform the grouping with a
|
|
|
<<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`,
|
|
|
@@ -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.
|
|
|
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]
|
|
|
----
|
|
|
@@ -400,7 +402,7 @@ The above query will result in:
|
|
|
----
|
|
|
// 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.
|
|
|
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
|
|
|
@@ -414,7 +416,7 @@ was simplified to the limits specified in the `size` parameter.
|
|
|
[[search-aggregations-metrics-geo-line-grouping-time-series-advantages]]
|
|
|
==== 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-time-series-aggregation,`time_series`>>
|
|
|
to group the geo-lines. However, there are some important differences in behaviour between the two cases.
|