this is what i refer to: https://www.elastic.co/guide/en/elasticsearch/reference/master/search-aggregations-bucket-terms-aggregation.html#_value_script_8

Seems a lot of the docs were out of date here. I have concerns this feature is actually used...

@rmuir and I spoke offline and the examples seem to be outdated in current master but work in 2.x so at least that is resolved. The question why we have this special value is still open and if we can / should move away from it?

Right thats the thing, we should optimize for common cases. This PR optimizes this _value so that its not going to do a bunch of per-document hash gets and puts, etc. Lucene expressions also already optimizes for it.

It was my understanding that this is how scripts interact with aggregations. So if this is true, then I want things to be performant, and i want the syntax to be easy.

LGTM on the Painless portion.

LGTM too

LGTM. Let's move forward.

@rmuir this feature works in 5.0.0-alpha2 and in master:

PUT t/t/1
{
  "foo": [5,10]
}

GET t/_search?size=0
{
  "aggs": {
    "foo": {
      "terms": {
        "field": "foo",
        "script": {
          "inline": "_value",
          "lang": "groovy"
        }
      }
    }
  }
}

There are two forms of scripts here: One where you don't specify the field, which is called once per doc, and one where you DO specify the field, which is called once per field _value.

@rmuir this feature works in 5.0.0-alpha2 and in master:

The confusion here was caused by the 5.0 docs not having script/inline but having what @s1monw called "1.x style scripting". So when i chased down this _value to see what it was all about: none of the examples worked. And there was not a lone rest test in the system using the feature (second problem)!

I think we can fix the docs side, I would like to convert them all to painless anyway and also make them use the special notation so they are tested.

ah ok - thanks for the explanation