non-binary gender option in term aggr. example (#19188)

Leon Weidauer · clintongormley · commit 1297a707da7b · 2016-07-01T14:59:03.000+02:00
* non-binary gender option in term aggr. example

* replace gender with music genre for term aggregation docs
diff --git a/docs/reference/aggregations/bucket/terms-aggregation.asciidoc b/docs/reference/aggregations/bucket/terms-aggregation.asciidoc
@@ -9,8 +9,8 @@ Example:
 --------------------------------------------------
 {
     "aggs" : {
-        "genders" : {
-            "terms" : { "field" : "gender" }
+        "genres" : {
+            "terms" : { "field" : "genre" }
         }
     }
 }
@@ -24,16 +24,20 @@ Response:
     ...
 
     "aggregations" : {
-        "genders" : {
+        "genres" : {
             "doc_count_error_upper_bound": 0, <1>
             "sum_other_doc_count": 0, <2>
             "buckets" : [ <3>
                 {
-                    "key" : "male",
+                    "key" : "jazz",
                     "doc_count" : 10
                 },
                 {
-                    "key" : "female",
+                    "key" : "rock",
+                    "doc_count" : 10
+                },
+                {
+                    "key" : "electronic",
                     "doc_count" : 10
                 },
             ]
@@ -247,9 +251,9 @@ Ordering the buckets by their `doc_count` in an ascending manner:
 --------------------------------------------------
 {
     "aggs" : {
-        "genders" : {
+        "genres" : {
             "terms" : {
-                "field" : "gender",
+                "field" : "genre",
                 "order" : { "_count" : "asc" }
             }
         }
@@ -263,9 +267,9 @@ Ordering the buckets alphabetically by their terms in an ascending manner:
 --------------------------------------------------
 {
     "aggs" : {
-        "genders" : {
+        "genres" : {
             "terms" : {
-                "field" : "gender",
+                "field" : "genre",
                 "order" : { "_term" : "asc" }
             }
         }
@@ -280,13 +284,13 @@ Ordering the buckets by single value metrics sub-aggregation (identified by the
 --------------------------------------------------
 {
     "aggs" : {
-        "genders" : {
+        "genres" : {
             "terms" : {
-                "field" : "gender",
-                "order" : { "avg_height" : "desc" }
+                "field" : "genre",
+                "order" : { "avg_play_count" : "desc" }
             },
             "aggs" : {
-                "avg_height" : { "avg" : { "field" : "height" } }
+                "avg_play_count" : { "avg" : { "field" : "play_count" } }
             }
         }
     }
@@ -299,13 +303,13 @@ Ordering the buckets by multi value metrics sub-aggregation (identified by the a
 --------------------------------------------------
 {
     "aggs" : {
-        "genders" : {
+        "genres" : {
             "terms" : {
-                "field" : "gender",
-                "order" : { "height_stats.avg" : "desc" }
+                "field" : "genre",
+                "order" : { "playback_stats.avg" : "desc" }
             },
             "aggs" : {
-                "height_stats" : { "stats" : { "field" : "height" } }
+                "playback_stats" : { "stats" : { "field" : "play_count" } }
             }
         }
     }
@@ -343,14 +347,14 @@ PATH                :=  <AGG_NAME>[<AGG_SEPARATOR><AGG_NAME>]*[<METRIC_SEPARATOR
     "aggs" : {
         "countries" : {
             "terms" : {
-                "field" : "address.country",
-                "order" : { "females>height_stats.avg" : "desc" }
+                "field" : "artist.country",
+                "order" : { "rock>playback_stats.avg" : "desc" }
             },
             "aggs" : {
-                "females" : {
-                    "filter" : { "term" : { "gender" :  "female" }},
+                "rock" : {
+                    "filter" : { "term" : { "genre" :  "rock" }},
                     "aggs" : {
-                        "height_stats" : { "stats" : { "field" : "height" }}
+                        "playback_stats" : { "stats" : { "field" : "play_count" }}
                     }
                 }
             }
@@ -359,7 +363,7 @@ PATH                :=  <AGG_NAME>[<AGG_SEPARATOR><AGG_NAME>]*[<METRIC_SEPARATOR
 }
 --------------------------------------------------
 
-The above will sort the countries buckets based on the average height among the female population.
+The above will sort the artist's countries buckets based on the average play count among the rock songs.
 
 Multiple criteria can be used to order the buckets by providing an array of order criteria such as the following:
 
@@ -369,14 +373,14 @@ Multiple criteria can be used to order the buckets by providing an array of orde
     "aggs" : {
         "countries" : {
             "terms" : {
-                "field" : "address.country",
-                "order" : [ { "females>height_stats.avg" : "desc" }, { "_count" : "desc" } ]
+                "field" : "artist.country",
+                "order" : [ { "rock>playback_stats.avg" : "desc" }, { "_count" : "desc" } ]
             },
             "aggs" : {
-                "females" : {
-                    "filter" : { "term" : { "gender" : { "female" }}},
+                "rock" : {
+                    "filter" : { "term" : { "genre" : { "rock" }}},
                     "aggs" : {
-                        "height_stats" : { "stats" : { "field" : "height" }}
+                        "playback_stats" : { "stats" : { "field" : "play_count" }}
                     }
                 }
             }
@@ -385,7 +389,7 @@ Multiple criteria can be used to order the buckets by providing an array of orde
 }
 --------------------------------------------------
 
-The above will sort the countries buckets based on the average height among the female population and then by
+The above will sort the artist's countries buckets based on the average play count among the rock songs and then by
 their `doc_count` in descending order.
 
 NOTE: In the event that two buckets share the same values for all order criteria the bucket's term value is used as a
@@ -439,10 +443,10 @@ Generating the terms using a script:
 --------------------------------------------------
 {
     "aggs" : {
-        "genders" : {
+        "genres" : {
             "terms" : {
                 "script" : {
-                    "inline": "doc['gender'].value"
+                    "inline": "doc['genre'].value"
                     "lang": "painless"
                 }
             }
@@ -457,12 +461,12 @@ This will interpret the `script` parameter as an `inline` script with the defaul
 --------------------------------------------------
 {
     "aggs" : {
-        "genders" : {
+        "genres" : {
             "terms" : {
                 "script" : {
                     "file": "my_script",
                     "params": {
-                        "field": "gender"
+                        "field": "genre"
                     }
                 }
             }
@@ -480,11 +484,11 @@ TIP: for indexed scripts replace the `file` parameter with an `id` parameter.
 --------------------------------------------------
 {
     "aggs" : {
-        "genders" : {
+        "genres" : {
             "terms" : {
-                "field" : "gender",
+                "field" : "gendre",
                 "script" : {
-                    "inline" : "'Gender: ' +_value"
+                    "inline" : "'Genre: ' +_value"
                     "lang" : "painless"
                 }
             }

Original file line number	Diff line number	Diff line change
`@@ -9,8 +9,8 @@ Example:`
`9`	`9`	`--------------------------------------------------`
`10`	`10`	`{`
`11`	`11`	`"aggs" : {`
`12`		`- "genders" : {`
`13`		`- "terms" : { "field" : "gender" }`
	`12`	`+ "genres" : {`
	`13`	`+ "terms" : { "field" : "genre" }`
`14`	`14`	`}`
`15`	`15`	`}`
`16`	`16`	`}`
`@@ -24,16 +24,20 @@ Response:`
`24`	`24`	`...`
`25`	`25`
`26`	`26`	`"aggregations" : {`
`27`		`- "genders" : {`
	`27`	`+ "genres" : {`
`28`	`28`	`"doc_count_error_upper_bound": 0, <1>`
`29`	`29`	`"sum_other_doc_count": 0, <2>`
`30`	`30`	`"buckets" : [ <3>`
`31`	`31`	`{`
`32`		`- "key" : "male",`
	`32`	`+ "key" : "jazz",`
`33`	`33`	`"doc_count" : 10`
`34`	`34`	`},`
`35`	`35`	`{`
`36`		`- "key" : "female",`
	`36`	`+ "key" : "rock",`
	`37`	`+ "doc_count" : 10`
	`38`	`+ },`
	`39`	`+ {`
	`40`	`+ "key" : "electronic",`
`37`	`41`	`"doc_count" : 10`
`38`	`42`	`},`
`39`	`43`	`]`
@@ -247,9 +251,9 @@ Ordering the buckets by their `doc_count` in an ascending manner:
`247`	`251`	`--------------------------------------------------`
`248`	`252`	`{`
`249`	`253`	`"aggs" : {`
`250`		`- "genders" : {`
	`254`	`+ "genres" : {`
`251`	`255`	`"terms" : {`
`252`		`- "field" : "gender",`
	`256`	`+ "field" : "genre",`
`253`	`257`	`"order" : { "_count" : "asc" }`
`254`	`258`	`}`
`255`	`259`	`}`
`@@ -263,9 +267,9 @@ Ordering the buckets alphabetically by their terms in an ascending manner:`
`263`	`267`	`--------------------------------------------------`
`264`	`268`	`{`
`265`	`269`	`"aggs" : {`
`266`		`- "genders" : {`
	`270`	`+ "genres" : {`
`267`	`271`	`"terms" : {`
`268`		`- "field" : "gender",`
	`272`	`+ "field" : "genre",`
`269`	`273`	`"order" : { "_term" : "asc" }`
`270`	`274`	`}`
`271`	`275`	`}`
`@@ -280,13 +284,13 @@ Ordering the buckets by single value metrics sub-aggregation (identified by the`
`280`	`284`	`--------------------------------------------------`
`281`	`285`	`{`
`282`	`286`	`"aggs" : {`
`283`		`- "genders" : {`
	`287`	`+ "genres" : {`
`284`	`288`	`"terms" : {`
`285`		`- "field" : "gender",`
`286`		`- "order" : { "avg_height" : "desc" }`
	`289`	`+ "field" : "genre",`
	`290`	`+ "order" : { "avg_play_count" : "desc" }`
`287`	`291`	`},`
`288`	`292`	`"aggs" : {`
`289`		`- "avg_height" : { "avg" : { "field" : "height" } }`
	`293`	`+ "avg_play_count" : { "avg" : { "field" : "play_count" } }`
`290`	`294`	`}`
`291`	`295`	`}`
`292`	`296`	`}`
`@@ -299,13 +303,13 @@ Ordering the buckets by multi value metrics sub-aggregation (identified by the a`
`299`	`303`	`--------------------------------------------------`
`300`	`304`	`{`
`301`	`305`	`"aggs" : {`
`302`		`- "genders" : {`
	`306`	`+ "genres" : {`
`303`	`307`	`"terms" : {`
`304`		`- "field" : "gender",`
`305`		`- "order" : { "height_stats.avg" : "desc" }`
	`308`	`+ "field" : "genre",`
	`309`	`+ "order" : { "playback_stats.avg" : "desc" }`
`306`	`310`	`},`
`307`	`311`	`"aggs" : {`
`308`		`- "height_stats" : { "stats" : { "field" : "height" } }`
	`312`	`+ "playback_stats" : { "stats" : { "field" : "play_count" } }`
`309`	`313`	`}`
`310`	`314`	`}`
`311`	`315`	`}`
`@@ -343,14 +347,14 @@ PATH := <AGG_NAME>[<AGG_SEPARATOR><AGG_NAME>]*[<METRIC_SEPARATOR`
`343`	`347`	`"aggs" : {`
`344`	`348`	`"countries" : {`
`345`	`349`	`"terms" : {`
`346`		`- "field" : "address.country",`
`347`		`- "order" : { "females>height_stats.avg" : "desc" }`
	`350`	`+ "field" : "artist.country",`
	`351`	`+ "order" : { "rock>playback_stats.avg" : "desc" }`
`348`	`352`	`},`
`349`	`353`	`"aggs" : {`
`350`		`- "females" : {`
`351`		`- "filter" : { "term" : { "gender" : "female" }},`
	`354`	`+ "rock" : {`
	`355`	`+ "filter" : { "term" : { "genre" : "rock" }},`
`352`	`356`	`"aggs" : {`
`353`		`- "height_stats" : { "stats" : { "field" : "height" }}`
	`357`	`+ "playback_stats" : { "stats" : { "field" : "play_count" }}`
`354`	`358`	`}`
`355`	`359`	`}`
`356`	`360`	`}`
`@@ -359,7 +363,7 @@ PATH := <AGG_NAME>[<AGG_SEPARATOR><AGG_NAME>]*[<METRIC_SEPARATOR`
`359`	`363`	`}`
`360`	`364`	`--------------------------------------------------`
`361`	`365`
`362`		`-The above will sort the countries buckets based on the average height among the female population.`
	`366`	`+The above will sort the artist's countries buckets based on the average play count among the rock songs.`
`363`	`367`
`364`	`368`	`Multiple criteria can be used to order the buckets by providing an array of order criteria such as the following:`
`365`	`369`
`@@ -369,14 +373,14 @@ Multiple criteria can be used to order the buckets by providing an array of orde`
`369`	`373`	`"aggs" : {`
`370`	`374`	`"countries" : {`
`371`	`375`	`"terms" : {`
`372`		`- "field" : "address.country",`
`373`		`- "order" : [ { "females>height_stats.avg" : "desc" }, { "_count" : "desc" } ]`
	`376`	`+ "field" : "artist.country",`
	`377`	`+ "order" : [ { "rock>playback_stats.avg" : "desc" }, { "_count" : "desc" } ]`
`374`	`378`	`},`
`375`	`379`	`"aggs" : {`
`376`		`- "females" : {`
`377`		`- "filter" : { "term" : { "gender" : { "female" }}},`
	`380`	`+ "rock" : {`
	`381`	`+ "filter" : { "term" : { "genre" : { "rock" }}},`
`378`	`382`	`"aggs" : {`
`379`		`- "height_stats" : { "stats" : { "field" : "height" }}`
	`383`	`+ "playback_stats" : { "stats" : { "field" : "play_count" }}`
`380`	`384`	`}`
`381`	`385`	`}`
`382`	`386`	`}`
`@@ -385,7 +389,7 @@ Multiple criteria can be used to order the buckets by providing an array of orde`
`385`	`389`	`}`
`386`	`390`	`--------------------------------------------------`
`387`	`391`
`388`		`-The above will sort the countries buckets based on the average height among the female population and then by`
	`392`	`+The above will sort the artist's countries buckets based on the average play count among the rock songs and then by`
`389`	`393`	their `doc_count` in descending order.
`390`	`394`
`391`	`395`	`NOTE: In the event that two buckets share the same values for all order criteria the bucket's term value is used as a`
`@@ -439,10 +443,10 @@ Generating the terms using a script:`
`439`	`443`	`--------------------------------------------------`
`440`	`444`	`{`
`441`	`445`	`"aggs" : {`
`442`		`- "genders" : {`
	`446`	`+ "genres" : {`
`443`	`447`	`"terms" : {`
`444`	`448`	`"script" : {`
`445`		`- "inline": "doc['gender'].value"`
	`449`	`+ "inline": "doc['genre'].value"`
`446`	`450`	`"lang": "painless"`
`447`	`451`	`}`
`448`	`452`	`}`
@@ -457,12 +461,12 @@ This will interpret the `script` parameter as an `inline` script with the defaul
`457`	`461`	`--------------------------------------------------`
`458`	`462`	`{`
`459`	`463`	`"aggs" : {`
`460`		`- "genders" : {`
	`464`	`+ "genres" : {`
`461`	`465`	`"terms" : {`
`462`	`466`	`"script" : {`
`463`	`467`	`"file": "my_script",`
`464`	`468`	`"params": {`
`465`		`- "field": "gender"`
	`469`	`+ "field": "genre"`
`466`	`470`	`}`
`467`	`471`	`}`
`468`	`472`	`}`
@@ -480,11 +484,11 @@ TIP: for indexed scripts replace the `file` parameter with an `id` parameter.
`480`	`484`	`--------------------------------------------------`
`481`	`485`	`{`
`482`	`486`	`"aggs" : {`
`483`		`- "genders" : {`
	`487`	`+ "genres" : {`
`484`	`488`	`"terms" : {`
`485`		`- "field" : "gender",`
	`489`	`+ "field" : "gendre",`
`486`	`490`	`"script" : {`
`487`		`- "inline" : "'Gender: ' +_value"`
	`491`	`+ "inline" : "'Genre: ' +_value"`
`488`	`492`	`"lang" : "painless"`
`489`	`493`	`}`
`490`	`494`	`}`