Update aggs reference documentation for 'keyed' options (#23758)

Add 'keyed' parameter documentation for following:
 - Date Histogram Aggregation
 - Date Range Aggregation
 - Geo Distance Aggregation
 - Histogram Aggregation
 - IP range aggregation
 - Percentiles Aggregation
 - Percentile Ranks Aggregation

docs/reference/aggregations/bucket/datehistogram-aggregation.asciidoc

@@ -302,6 +302,60 @@ documents into buckets starting at 6am:
 NOTE: The start `offset` of each bucket is calculated after the `time_zone`
 adjustments have been made.
 
+==== Keyed Response
+
+Setting the `keyed` flag to `true` will associate a unique string key with each bucket and return the ranges as a hash rather than an array:
+
+[source,js]
+--------------------------------------------------
+POST /sales/_search?size=0
+{
+    "aggs" : {
+        "sales_over_time" : {
+            "date_histogram" : {
+                "field" : "date",
+                "interval" : "1M",
+                "format" : "yyyy-MM-dd",
+                "keyed": true
+            }
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:sales]
+
+Response:
+
+[source,js]
+--------------------------------------------------
+{
+    ...
+    "aggregations": {
+        "sales_over_time": {
+            "buckets": {
+                "2015-01-01": {
+                    "key_as_string": "2015-01-01",
+                    "key": 1420070400000,
+                    "doc_count": 3
+                },
+                "2015-02-01": {
+                    "key_as_string": "2015-02-01",
+                    "key": 1422748800000,
+                    "doc_count": 2
+                },
+                "2015-03-01": {
+                    "key_as_string": "2015-03-01",
+                    "key": 1425168000000,
+                    "doc_count": 2
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]
+
 ==== Scripts
 
 Like with the normal <<search-aggregations-bucket-histogram-aggregation,histogram>>, both document level scripts and

docs/reference/aggregations/bucket/daterange-aggregation.asciidoc

@@ -153,3 +153,109 @@ POST /sales/_search?size=0
 
 <1> This date will be converted to `2016-02-15T00:00:00.000+01:00`.
 <2> `now/d` will be rounded to the beginning of the day in the CET time zone.
+
+==== Keyed Response
+
+Setting the `keyed` flag to `true` will associate a unique string key with each bucket and return the ranges as a hash rather than an array:
+
+[source,js]
+--------------------------------------------------
+POST /sales/_search?size=0
+{
+    "aggs": {
+        "range": {
+            "date_range": {
+                "field": "date",
+                "format": "MM-yyy",
+                "ranges": [
+                    { "to": "now-10M/M" },
+                    { "from": "now-10M/M" }
+                ],
+                "keyed": true
+            }
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:sales s/now-10M\/M/10-2015/]
+
+Response:
+
+[source,js]
+--------------------------------------------------
+{
+    ...
+    "aggregations": {
+        "range": {
+            "buckets": {
+                "*-10-2015": {
+                    "to": 1.4436576E12,
+                    "to_as_string": "10-2015",
+                    "doc_count": 7
+                },
+                "10-2015-*": {
+                    "from": 1.4436576E12,
+                    "from_as_string": "10-2015",
+                    "doc_count": 0
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]
+
+It is also possible to customize the key for each range:
+
+[source,js]
+--------------------------------------------------
+POST /sales/_search?size=0
+{
+    "aggs": {
+        "range": {
+            "date_range": {
+                "field": "date",
+                "format": "MM-yyy",
+                "ranges": [
+                    { "from": "01-2015",  "to": "03-2015", "key": "quarter_01" },
+                    { "from": "03-2015", "to": "06-2015", "key": "quarter_02" }
+                ],
+                "keyed": true
+            }
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:sales]
+
+Response:
+
+[source,js]
+--------------------------------------------------
+{
+    ...
+    "aggregations": {
+        "range": {
+            "buckets": {
+                "quarter_01": {
+                    "from": 1.4200704E12,
+                    "from_as_string": "01-2015",
+                    "to": 1.425168E12,
+                    "to_as_string": "03-2015",
+                    "doc_count": 5
+                },
+                "quarter_02": {
+                    "from": 1.425168E12,
+                    "from_as_string": "03-2015",
+                    "to": 1.4331168E12,
+                    "to_as_string": "06-2015",
+                    "doc_count": 2
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]

docs/reference/aggregations/bucket/geodistance-aggregation.asciidoc

@@ -142,3 +142,116 @@ POST /museums/_search?size=0
 --------------------------------------------------
 // CONSOLE
 // TEST[continued]
+
+==== Keyed Response
+
+Setting the `keyed` flag to `true` will associate a unique string key with each bucket and return the ranges as a hash rather than an array:
+
+[source,js]
+--------------------------------------------------
+POST /museums/_search?size=0
+{
+    "aggs" : {
+        "rings_around_amsterdam" : {
+            "geo_distance" : {
+                "field" : "location",
+                "origin" : "52.3760, 4.894",
+                "ranges" : [
+                    { "to" : 100000 },
+                    { "from" : 100000, "to" : 300000 },
+                    { "from" : 300000 }
+                ],
+                "keyed": true
+            }
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+Response:
+
+[source,js]
+--------------------------------------------------
+{
+    ...
+    "aggregations": {
+        "rings_around_amsterdam" : {
+            "buckets": {
+                "*-100000.0": {
+                    "from": 0.0,
+                    "to": 100000.0,
+                    "doc_count": 3
+                },
+                "100000.0-300000.0": {
+                    "from": 100000.0,
+                    "to": 300000.0,
+                    "doc_count": 1
+                },
+                "300000.0-*": {
+                    "from": 300000.0,
+                    "doc_count": 2
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
+
+It is also possible to customize the key for each range:
+
+[source,js]
+--------------------------------------------------
+POST /museums/_search?size=0
+{
+    "aggs" : {
+        "rings_around_amsterdam" : {
+            "geo_distance" : {
+                "field" : "location",
+                "origin" : "52.3760, 4.894",
+                "ranges" : [
+                    { "to" : 100000, "key": "first_ring" },
+                    { "from" : 100000, "to" : 300000, "key": "second_ring" },
+                    { "from" : 300000, "key": "third_ring" }
+                ],
+                "keyed": true
+            }
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+Response:
+
+[source,js]
+--------------------------------------------------
+{
+    ...
+    "aggregations": {
+        "rings_around_amsterdam" : {
+            "buckets": {
+                "first_ring": {
+                    "from": 0.0,
+                    "to": 100000.0,
+                    "doc_count": 3
+                },
+                "second_ring": {
+                    "from": 100000.0,
+                    "to": 300000.0,
+                    "doc_count": 1
+                },
+                "third_ring": {
+                    "from": 300000.0,
+                    "doc_count": 2
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
+

docs/reference/aggregations/bucket/iprange-aggregation.asciidoc

@@ -90,3 +90,93 @@ Response:
     }
 }
 --------------------------------------------------
+
+==== Keyed Response
+
+Setting the `keyed` flag to `true` will associate a unique string key with each bucket and return the ranges as a hash rather than an array:
+
+[source,js]
+--------------------------------------------------
+{
+    "aggs": {
+        "ip_ranges": {
+            "ip_range": {
+                "field": "remote_ip",
+                "ranges": [
+                    { "to" : "10.0.0.5" },
+                    { "from" : "10.0.0.5" }
+                ],
+                "keyed": true
+            }
+        }
+    }
+}
+--------------------------------------------------
+
+Response:
+
+[source,js]
+--------------------------------------------------
+{
+    ...
+
+    "aggregations": {
+        "ip_ranges": {
+            "buckets": {
+                "*-10.0.0.5": {
+                    "to": "10.0.0.5",
+                    "doc_count": 1462
+                },
+                "10.0.0.5-*": {
+                    "from": "10.0.0.5",
+                    "doc_count": 50000
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------
+
+It is also possible to customize the key for each range:
+
+[source,js]
+--------------------------------------------------
+{
+    "aggs": {
+        "ip_ranges": {
+            "ip_range": {
+                "field": "remote_ip",
+                "ranges": [
+                    { "key": "infinity", "to" : "10.0.0.5" },
+                    { "key": "and-beyond", "from" : "10.0.0.5" }
+                ],
+                "keyed": true
+            }
+        }
+    }
+}
+--------------------------------------------------
+
+Response:
+
+[source,js]
+--------------------------------------------------
+{
+    ...
+
+    "aggregations": {
+        "ip_ranges": {
+            "buckets": {
+                "infinity": {
+                    "to": "10.0.0.5",
+                    "doc_count": 1462
+                },
+                "and-beyond": {
+                    "from": "10.0.0.5",
+                    "doc_count": 50000
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------

docs/reference/aggregations/metrics/percentile-aggregation.asciidoc

@@ -86,7 +86,78 @@ must be a value between 0-100 inclusive):
 --------------------------------------------------
 <1> Use the `percents` parameter to specify particular percentiles to calculate
 
+==== Keyed Response
 
+By default the `keyed` flag is set to `true` which associates a unique string key with each bucket and returns the ranges as a hash rather than an array. Setting the `keyed` flag to `false` will disable this behavior:
+
+[source,js]
+--------------------------------------------------
+POST bank/account/_search?size=0
+{
+    "aggs": {
+        "balance_outlier": {
+            "percentiles": {
+                "field": "balance",
+                "keyed": false
+            }
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:bank]
+
+Response:
+
+[source,js]
+--------------------------------------------------
+{
+    ...
+
+    "aggregations": {
+        "balance_outlier": {
+            "values": [
+                {
+                    "key": 1.0,
+                    "value": 1462.8400000000001
+                },
+                {
+                    "key": 5.0,
+                    "value": 3591.85
+                },
+                {
+                    "key": 25.0,
+                    "value": 13709.333333333334
+                },
+                {
+                    "key": 50.0,
+                    "value": 26020.11666666667
+                },
+                {
+                    "key": 75.0,
+                    "value": 38139.648148148146
+                },
+                {
+                    "key": 95.0,
+                    "value": 47551.549999999996
+                },
+                {
+                    "key": 99.0,
+                    "value": 49339.16
+                }
+            ]
+        }
+    }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]
+// TESTRESPONSE[s/1462.8400000000001/$body.aggregations.balance_outlier.values.0.value/]
+// TESTRESPONSE[s/3591.85/$body.aggregations.balance_outlier.values.1.value/]
+// TESTRESPONSE[s/13709.333333333334/$body.aggregations.balance_outlier.values.2.value/]
+// TESTRESPONSE[s/26020.11666666667/$body.aggregations.balance_outlier.values.3.value/]
+// TESTRESPONSE[s/38139.648148148146/$body.aggregations.balance_outlier.values.4.value/]
+// TESTRESPONSE[s/47551.549999999996/$body.aggregations.balance_outlier.values.5.value/]
+// TESTRESPONSE[s/49339.16/$body.aggregations.balance_outlier.values.6.value/]
 
 ==== Script
 

docs/reference/aggregations/metrics/percentile-rank-aggregation.asciidoc

@@ -58,6 +58,54 @@ The response will look like this:
 From this information you can determine you are hitting the 99% load time target but not quite
 hitting the 95% load time target
 
+==== Keyed Response
+
+By default the `keyed` flag is set to `true` associates a unique string key with each bucket and returns the ranges as a hash rather than an array. Setting the `keyed` flag to `false` will disable this behavior:
+
+[source,js]
+--------------------------------------------------
+POST bank/account/_search?size=0
+{
+    "aggs": {
+        "balance_outlier": {
+            "percentile_ranks": {
+                "field": "balance",
+                "values": [25000, 50000],
+                "keyed": false
+            }
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[setup:bank]
+
+Response:
+
+[source,js]
+--------------------------------------------------
+{
+    ...
+
+    "aggregations": {
+        "balance_outlier": {
+            "values": [
+                {
+                    "key": 25000.0,
+                    "value": 48.537724935732655
+                },
+                {
+                    "key": 50000.0,
+                    "value": 99.85567010309278
+                }
+            ]
+        }
+    }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]
+// TESTRESPONSE[s/48.537724935732655/$body.aggregations.balance_outlier.values.0.value/]
+// TESTRESPONSE[s/99.85567010309278/$body.aggregations.balance_outlier.values.1.value/]
 
 ==== Script