Skip to content

Commit 24dc867

Browse files
sudo-suhasjavanna
sudo-suhas
authored and
javanna
committed
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
1 parent 784ec02 commit 24dc867

File tree

6 files changed

+482
-0
lines changed

6 files changed

+482
-0
lines changed

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

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -302,6 +302,60 @@ documents into buckets starting at 6am:
302302
NOTE: The start `offset` of each bucket is calculated after the `time_zone`
303303
adjustments have been made.
304304

305+
==== Keyed Response
306+
307+
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:
308+
309+
[source,js]
310+
--------------------------------------------------
311+
POST /sales/_search?size=0
312+
{
313+
"aggs" : {
314+
"sales_over_time" : {
315+
"date_histogram" : {
316+
"field" : "date",
317+
"interval" : "1M",
318+
"format" : "yyyy-MM-dd",
319+
"keyed": true
320+
}
321+
}
322+
}
323+
}
324+
--------------------------------------------------
325+
// CONSOLE
326+
// TEST[setup:sales]
327+
328+
Response:
329+
330+
[source,js]
331+
--------------------------------------------------
332+
{
333+
...
334+
"aggregations": {
335+
"sales_over_time": {
336+
"buckets": {
337+
"2015-01-01": {
338+
"key_as_string": "2015-01-01",
339+
"key": 1420070400000,
340+
"doc_count": 3
341+
},
342+
"2015-02-01": {
343+
"key_as_string": "2015-02-01",
344+
"key": 1422748800000,
345+
"doc_count": 2
346+
},
347+
"2015-03-01": {
348+
"key_as_string": "2015-03-01",
349+
"key": 1425168000000,
350+
"doc_count": 2
351+
}
352+
}
353+
}
354+
}
355+
}
356+
--------------------------------------------------
357+
// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]
358+
305359
==== Scripts
306360

307361
Like with the normal <<search-aggregations-bucket-histogram-aggregation,histogram>>, both document level scripts and

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

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,3 +153,109 @@ POST /sales/_search?size=0
153153

154154
<1> This date will be converted to `2016-02-15T00:00:00.000+01:00`.
155155
<2> `now/d` will be rounded to the beginning of the day in the CET time zone.
156+
157+
==== Keyed Response
158+
159+
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:
160+
161+
[source,js]
162+
--------------------------------------------------
163+
POST /sales/_search?size=0
164+
{
165+
"aggs": {
166+
"range": {
167+
"date_range": {
168+
"field": "date",
169+
"format": "MM-yyy",
170+
"ranges": [
171+
{ "to": "now-10M/M" },
172+
{ "from": "now-10M/M" }
173+
],
174+
"keyed": true
175+
}
176+
}
177+
}
178+
}
179+
--------------------------------------------------
180+
// CONSOLE
181+
// TEST[setup:sales s/now-10M\/M/10-2015/]
182+
183+
Response:
184+
185+
[source,js]
186+
--------------------------------------------------
187+
{
188+
...
189+
"aggregations": {
190+
"range": {
191+
"buckets": {
192+
"*-10-2015": {
193+
"to": 1.4436576E12,
194+
"to_as_string": "10-2015",
195+
"doc_count": 7
196+
},
197+
"10-2015-*": {
198+
"from": 1.4436576E12,
199+
"from_as_string": "10-2015",
200+
"doc_count": 0
201+
}
202+
}
203+
}
204+
}
205+
}
206+
--------------------------------------------------
207+
// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]
208+
209+
It is also possible to customize the key for each range:
210+
211+
[source,js]
212+
--------------------------------------------------
213+
POST /sales/_search?size=0
214+
{
215+
"aggs": {
216+
"range": {
217+
"date_range": {
218+
"field": "date",
219+
"format": "MM-yyy",
220+
"ranges": [
221+
{ "from": "01-2015", "to": "03-2015", "key": "quarter_01" },
222+
{ "from": "03-2015", "to": "06-2015", "key": "quarter_02" }
223+
],
224+
"keyed": true
225+
}
226+
}
227+
}
228+
}
229+
--------------------------------------------------
230+
// CONSOLE
231+
// TEST[setup:sales]
232+
233+
Response:
234+
235+
[source,js]
236+
--------------------------------------------------
237+
{
238+
...
239+
"aggregations": {
240+
"range": {
241+
"buckets": {
242+
"quarter_01": {
243+
"from": 1.4200704E12,
244+
"from_as_string": "01-2015",
245+
"to": 1.425168E12,
246+
"to_as_string": "03-2015",
247+
"doc_count": 5
248+
},
249+
"quarter_02": {
250+
"from": 1.425168E12,
251+
"from_as_string": "03-2015",
252+
"to": 1.4331168E12,
253+
"to_as_string": "06-2015",
254+
"doc_count": 2
255+
}
256+
}
257+
}
258+
}
259+
}
260+
--------------------------------------------------
261+
// TESTRESPONSE[s/\.\.\./"took": $body.took,"timed_out": false,"_shards": $body._shards,"hits": $body.hits,/]

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

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,3 +145,116 @@ POST /museums/_search?size=0
145145
--------------------------------------------------
146146
// CONSOLE
147147
// TEST[continued]
148+
149+
==== Keyed Response
150+
151+
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:
152+
153+
[source,js]
154+
--------------------------------------------------
155+
POST /museums/_search?size=0
156+
{
157+
"aggs" : {
158+
"rings_around_amsterdam" : {
159+
"geo_distance" : {
160+
"field" : "location",
161+
"origin" : "52.3760, 4.894",
162+
"ranges" : [
163+
{ "to" : 100000 },
164+
{ "from" : 100000, "to" : 300000 },
165+
{ "from" : 300000 }
166+
],
167+
"keyed": true
168+
}
169+
}
170+
}
171+
}
172+
--------------------------------------------------
173+
// CONSOLE
174+
// TEST[continued]
175+
176+
Response:
177+
178+
[source,js]
179+
--------------------------------------------------
180+
{
181+
...
182+
"aggregations": {
183+
"rings_around_amsterdam" : {
184+
"buckets": {
185+
"*-100000.0": {
186+
"from": 0.0,
187+
"to": 100000.0,
188+
"doc_count": 3
189+
},
190+
"100000.0-300000.0": {
191+
"from": 100000.0,
192+
"to": 300000.0,
193+
"doc_count": 1
194+
},
195+
"300000.0-*": {
196+
"from": 300000.0,
197+
"doc_count": 2
198+
}
199+
}
200+
}
201+
}
202+
}
203+
--------------------------------------------------
204+
// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
205+
206+
It is also possible to customize the key for each range:
207+
208+
[source,js]
209+
--------------------------------------------------
210+
POST /museums/_search?size=0
211+
{
212+
"aggs" : {
213+
"rings_around_amsterdam" : {
214+
"geo_distance" : {
215+
"field" : "location",
216+
"origin" : "52.3760, 4.894",
217+
"ranges" : [
218+
{ "to" : 100000, "key": "first_ring" },
219+
{ "from" : 100000, "to" : 300000, "key": "second_ring" },
220+
{ "from" : 300000, "key": "third_ring" }
221+
],
222+
"keyed": true
223+
}
224+
}
225+
}
226+
}
227+
--------------------------------------------------
228+
// CONSOLE
229+
// TEST[continued]
230+
231+
Response:
232+
233+
[source,js]
234+
--------------------------------------------------
235+
{
236+
...
237+
"aggregations": {
238+
"rings_around_amsterdam" : {
239+
"buckets": {
240+
"first_ring": {
241+
"from": 0.0,
242+
"to": 100000.0,
243+
"doc_count": 3
244+
},
245+
"second_ring": {
246+
"from": 100000.0,
247+
"to": 300000.0,
248+
"doc_count": 1
249+
},
250+
"third_ring": {
251+
"from": 300000.0,
252+
"doc_count": 2
253+
}
254+
}
255+
}
256+
}
257+
}
258+
--------------------------------------------------
259+
// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
260+

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

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,3 +90,93 @@ Response:
9090
}
9191
}
9292
--------------------------------------------------
93+
94+
==== Keyed Response
95+
96+
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:
97+
98+
[source,js]
99+
--------------------------------------------------
100+
{
101+
"aggs": {
102+
"ip_ranges": {
103+
"ip_range": {
104+
"field": "remote_ip",
105+
"ranges": [
106+
{ "to" : "10.0.0.5" },
107+
{ "from" : "10.0.0.5" }
108+
],
109+
"keyed": true
110+
}
111+
}
112+
}
113+
}
114+
--------------------------------------------------
115+
116+
Response:
117+
118+
[source,js]
119+
--------------------------------------------------
120+
{
121+
...
122+
123+
"aggregations": {
124+
"ip_ranges": {
125+
"buckets": {
126+
"*-10.0.0.5": {
127+
"to": "10.0.0.5",
128+
"doc_count": 1462
129+
},
130+
"10.0.0.5-*": {
131+
"from": "10.0.0.5",
132+
"doc_count": 50000
133+
}
134+
}
135+
}
136+
}
137+
}
138+
--------------------------------------------------
139+
140+
It is also possible to customize the key for each range:
141+
142+
[source,js]
143+
--------------------------------------------------
144+
{
145+
"aggs": {
146+
"ip_ranges": {
147+
"ip_range": {
148+
"field": "remote_ip",
149+
"ranges": [
150+
{ "key": "infinity", "to" : "10.0.0.5" },
151+
{ "key": "and-beyond", "from" : "10.0.0.5" }
152+
],
153+
"keyed": true
154+
}
155+
}
156+
}
157+
}
158+
--------------------------------------------------
159+
160+
Response:
161+
162+
[source,js]
163+
--------------------------------------------------
164+
{
165+
...
166+
167+
"aggregations": {
168+
"ip_ranges": {
169+
"buckets": {
170+
"infinity": {
171+
"to": "10.0.0.5",
172+
"doc_count": 1462
173+
},
174+
"and-beyond": {
175+
"from": "10.0.0.5",
176+
"doc_count": 50000
177+
}
178+
}
179+
}
180+
}
181+
}
182+
--------------------------------------------------

0 commit comments

Comments
 (0)