Improve terms aggregation example

[debadair]

The first example on the terms agg page doesn't provide sample data and is somewhat misleading. For the example to work as-is, fielddata must be enabled on the genre field. Alternatively (preferably) you can use the keyword field, instead. Otherwise, you'll get the following error:

{"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"Fielddata is disabled on text fields by default. Set fielddata=true on [color] in order to load fielddata in memory by uninverting the inverted index. Note that this can however use significant memory. Alternatively use a keyword field instead."}],"

This sent someone looking at the Definitive Guide down a rabbit hole trying to run against 6.3.

https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html

https://www.elastic.co/blog/strings-are-dead-long-live-strings

[elasticmachine]

Pinging @elastic/es-search-aggs

[lonlylocly]

Hello, I really like the idea of this issue. I have seen how much confusion it makes to the newcomers that there are different types keyword and text and how they can be searched/aggregated. (A quick search on StackOverflow shows a bunch of related questions: https://stackoverflow.com/search?q=elasticsearch+terms+fielddata)

The terms aggregation documentation page seems a perfect place to resolve this confusion, and I also like the idea of adding the mapping and the sample data.

But I am having a couple of doubts that I would like to resolve before committing an enhancement.

Why do I think it is a good idea

Putting a mapping in the example will, first, make it clear which kind of data structure we are working with, and second, will give to a newcomer an idea that mappings exist and they are important (very often in the StackOverflow questions they do not post mappings making it extremely difficult to answer as-is). Just a bare curiosity of "what is this mapping thing?" would be enough to move a newcomer towards getting to know what the mapping is.

Adding sample data completes the example with possibility to copy-paste the data and try it on your own, which is also important for learning.

Why do I think it is not

The first doubt:
It does not look like mappings are generally put in the examples in the Elasticsearch documentation. Wouldn't adding a mapping in the example here break the general picture?

The second doubt:
Mappings and example documents will inevitably blow up the page visually, and the conciseness of the current version will be lost.

What do I propose

Having in mind these doubts I think it is better to put a "Note" section after GET /_search part or a footnote just inside the query example, saying something like this:

terms aggregation needs a field of type keyword or any other data type suitable for bucket aggregations. In order to use it with text you will need to enable fielddata.

This way we keep the conciseness of the example, we provide a complete explanation (the example would only cover keyword type, hiding the possibility to use text with fielddata, or vice versa), and do not break the visual impression.

Please tell me what you think about this.

[srensamblador]

I think a footnote in the query would be nice. Fielddata tend to give newcomers a bit of trouble (regarding newcomer students' usual problems).

I could add it if you want

[polyfractal]

@lonlylocly @srensamblador I think this sounds like a very reasonable addition. It's technically a problem for any aggregation, but tends to surface the most often on the Terms aggregation (due to dealing with text).

Please feel free to open a docs PR and we can see about adding something :) Thanks!

[EliuFlorez]

@lonlylocly @polyfractal To establish aggregation by multi-bucket, it is mandatory to set fielddata = true, that is, to obtain the title: "New York" in ["New", "York"]. Or, according to the documentation, can the multi-bucket be established in another way?

[polyfractal]

@EliuFlorez If you have multi-valued fields, field-data won't help convert it into "New York". They will be analyzed and tokenized separately, so you'll still have ["New", "York"]. I think you'll either need to make your fields not multi-valued, or potentially copy_to them into a new field.

But questions like this are better suited for the Discuss Forums

Closing since #38892 merged!

[EliuFlorez]

@polyfractal https://discuss.elastic.co/t/terms-aggregation-split-by-whitespace/171522