From 8b9f3316cc0455dc76bf24c4526de5c42303b374 Mon Sep 17 00:00:00 2001 From: Adam Locke Date: Fri, 18 Dec 2020 11:31:42 -0500 Subject: [PATCH] [DOCS] Adding headers in TOC for aggregation docs. (#66604) --- .../bucket/datehistogram-aggregation.asciidoc | 33 +++++++++++-------- .../metrics/geobounds-aggregation.asciidoc | 1 + .../metrics/geocentroid-aggregation.asciidoc | 1 + 3 files changed, 21 insertions(+), 14 deletions(-) diff --git a/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc b/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc index 44f5164a3e4b9..707f5251cb256 100644 --- a/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc +++ b/docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc @@ -56,7 +56,7 @@ will be removed in the future. ================================== [[calendar_intervals]] -===== Calendar intervals +==== Calendar intervals Calendar-aware intervals are configured with the `calendar_interval` parameter. You can specify calendar intervals using the unit name, such as `month`, or as a @@ -173,7 +173,7 @@ POST /sales/_search?size=0 // NOTCONSOLE [[fixed_intervals]] -===== Fixed intervals +==== Fixed intervals Fixed intervals are configured with the `fixed_interval` parameter. @@ -267,7 +267,7 @@ POST /sales/_search?size=0 // NOTCONSOLE [[datehistogram-aggregation-notes]] -===== Notes +==== Date histogram usage notes In all cases, when the specified end time does not exist, the actual end time is the closest available time after the specified end. @@ -282,17 +282,17 @@ As always, rigorous testing, especially around time-change events, will ensure that your time interval specification is what you intend it to be. -WARNING: -To avoid unexpected results, all connected servers and clients must sync to a -reliable network time service. +WARNING: To avoid unexpected results, all connected servers and clients must +sync to a reliable network time service. -NOTE: fractional time values are not supported, but you can address this by +NOTE: Fractional time values are not supported, but you can address this by shifting to another time unit (e.g., `1.5h` could instead be specified as `90m`). NOTE: You can also specify time values using abbreviations supported by <> parsing. -===== Keys +[[datehistogram-aggregation-keys]] +==== Keys Internally, a date is represented as a 64 bit number representing a timestamp in milliseconds-since-the-epoch (01/01/1970 midnight UTC). These timestamps are @@ -353,7 +353,8 @@ Response: -------------------------------------------------- // TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/] -===== Time zone +[[datehistogram-aggregation-time-zone]] +==== Time zone {es} stores date-times in Coordinated Universal Time (UTC). By default, all bucketing and rounding is also done in UTC. Use the `time_zone` parameter to indicate @@ -489,7 +490,7 @@ shorter intervals, like a `fixed_interval` of `12h`, where you'll have only a 11 bucket on the morning of 27 March when the DST shift happens. [[search-aggregations-bucket-datehistogram-offset]] -===== Offset +==== Offset // tag::offset-explanation[] Use the `offset` parameter to change the start value of each bucket by the @@ -562,7 +563,8 @@ NOTE: The start `offset` of each bucket is calculated after `time_zone` adjustments have been made. // end::offset-note[] -===== Keyed Response +[[date-histogram-keyed-response]] +==== Keyed Response Setting the `keyed` flag to `true` associates a unique string key with each bucket and returns the ranges as a hash rather than an array: @@ -616,7 +618,8 @@ Response: -------------------------------------------------- // TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/] -===== Scripts +[[date-histogram-scripts]] +==== Scripts As with the normal <>, both document-level scripts and @@ -632,6 +635,7 @@ For more information, see <> and <>. +[[date-histogram-missing-value]] ===== Missing value The `missing` parameter defines how to treat documents that are missing a value. @@ -658,6 +662,7 @@ POST /sales/_search?size=0 <1> Documents without a value in the `publish_date` field will fall into the same bucket as documents that have the value `2000-01-01`. +[[date-histogram-order]] ===== Order By default the returned buckets are sorted by their `key` ascending, but you can @@ -665,13 +670,13 @@ control the order using the `order` setting. This setting supports the same `order` functionality as <>. +[[date-histogram-aggregate-scripts]] ===== Using a script to aggregate by day of the week When you need to aggregate the results by day of the week, use a script that returns the day of the week: - -[source,console] +[source,console,id=datehistogram-aggregation-script-example] -------------------------------------------------- POST /sales/_search?size=0 { diff --git a/docs/reference/aggregations/metrics/geobounds-aggregation.asciidoc b/docs/reference/aggregations/metrics/geobounds-aggregation.asciidoc index a00cff2970062..51d551b67dbb2 100644 --- a/docs/reference/aggregations/metrics/geobounds-aggregation.asciidoc +++ b/docs/reference/aggregations/metrics/geobounds-aggregation.asciidoc @@ -82,6 +82,7 @@ The response for the above aggregation: [discrete] [role="xpack"] +[[geobounds-aggregation-geo-shape]] ==== Geo Bounds Aggregation on `geo_shape` fields The Geo Bounds Aggregation is also supported on `geo_shape` fields. diff --git a/docs/reference/aggregations/metrics/geocentroid-aggregation.asciidoc b/docs/reference/aggregations/metrics/geocentroid-aggregation.asciidoc index 8acb7e89e1468..2658ab6683d3c 100644 --- a/docs/reference/aggregations/metrics/geocentroid-aggregation.asciidoc +++ b/docs/reference/aggregations/metrics/geocentroid-aggregation.asciidoc @@ -150,6 +150,7 @@ The response for the above aggregation: [discrete] [role="xpack"] +[[geocentroid-aggregation-geo-shape]] ==== Geo Centroid Aggregation on `geo_shape` fields The centroid metric for geo-shapes is more nuanced than for points. The centroid of a specific aggregation bucket