Browse Source

[DOCS] Add tech preview admonition for geo line aggs on time-series data (#97844)

* Add tech preview admonition for time-series data

* Light editing
Abdon Pijpelink 2 years ago
parent
commit
e3c11016b9
1 changed files with 17 additions and 15 deletions
  1. 17 15
      docs/reference/aggregations/metrics/geoline-aggregation.asciidoc

+ 17 - 15
docs/reference/aggregations/metrics/geoline-aggregation.asciidoc

@@ -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.