Painless: Add Context Docs (#31190)

Adds documentation for each the variables and API available with each script context 
usable with a Painless script.

docs/painless/index.asciidoc

@@ -7,4 +7,6 @@ include::painless-getting-started.asciidoc[]
 
 include::painless-lang-spec.asciidoc[]
 
-include::painless-api-reference.asciidoc[]
+include::painless-contexts.asciidoc[]
+
+include::painless-api-reference.asciidoc[]

docs/painless/painless-contexts.asciidoc

@@ -0,0 +1,58 @@
+[[painless-contexts]]
+== Painless contexts
+
+:es_version: https://www.elastic.co/guide/en/elasticsearch/reference/master
+:xp_version: https://www.elastic.co/guide/en/x-pack/current
+
+A Painless script is evaluated within a context. Each context has values that
+are available as local variables, a whitelist that controls the available
+classes, and the methods and fields within those classes (API), and
+if and what type of value is returned.
+
+A Painless script is typically executed within one of the contexts in the table
+below. Note this is not necessarily a comprehensive list as custom plugins and
+specialized code may define new ways to use a Painless script.
+
+[options="header",cols="<1,<1,<1"]
+|====
+| Name                              | Painless Documentation
+                                    | Elasticsearch Documentation
+| Update                            | <<painless-update-context, Painless Documentation>>
+                                    | {es_version}/docs-update.html[Elasticsearch Documentation]
+| Update by query                   | <<painless-update-by-query-context, Painless Documentation>>
+                                    | {es_version}/docs-update-by-query.html[Elasticsearch Documentation]
+| Reindex                           | <<painless-reindex-context, Painless Documentation>>
+                                    | {es_version}/docs-reindex.html[Elasticsearch Documentation]
+| Sort                              | <<painless-sort-context, Painless Documentation>>
+                                    | {es_version}/search-request-sort.html[Elasticsearch Documentation]
+| Similarity                        | <<painless-similarity-context, Painless Documentation>>
+                                    | {es_version}/index-modules-similarity.html[Elasticsearch Documentation]
+| Weight                            | <<painless-similarity-context, Painless Documentation>>
+                                    | {es_version}/index-modules-similarity.html[Elasticsearch Documentation]
+| Score                             | <<painless-score-context, Painless Documentation>>
+                                    | {es_version}/query-dsl-function-score-query.html[Elasticsearch Documentation]
+| Field                             | <<painless-field-context, Painless Documentation>>
+                                    | {es_version}/search-request-script-fields.html[Elasticsearch Documentation]
+| Filter                            | <<painless-filter-context, Painless Documentation>>
+                                    | {es_version}/query-dsl-script-query.html[Elasticsearch Documentation]
+| Minimum should match              | <<painless-min-should-match-context, Painless Documentation>>
+                                    | {es_version}/query-dsl-terms-set-query.html[Elasticsearch Documentation]
+| Metric aggregation initialization | <<painless-metric-agg-init-context, Painless Documentation>>
+                                    | {es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation]
+| Metric aggregation map            | <<painless-metric-agg-map-context, Painless Documentation>>
+                                    | {es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation]
+| Metric aggregation combine        | <<painless-metric-agg-combine-context, Painless Documentation>>
+                                    | {es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation]
+| Metric aggregation reduce         | <<painless-metric-agg-reduce-context, Painless Documentation>>
+                                    | {es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation]
+| Bucket aggregation                | <<painless-bucket-agg-context, Painless Documentation>>
+                                    | {es_version}/search-aggregations-pipeline-bucket-script-aggregation.html[Elasticsearch Documentation]
+| Ingest processor                  | <<painless-ingest-processor-context, Painless Documentation>>
+                                    | {es_version}/script-processor.html[Elasticsearch Documentation]
+| Watcher condition                 | <<painless-watcher-condition-context, Painless Documentation>>
+                                    | {xp_version}/condition-script.html[Elasticsearch Documentation]
+| Watcher transform                 | <<painless-watcher-transform-context, Painless Documentation>>
+                                    | {xp_version}/transform-script.html[Elasticsearch Documentation]
+|====
+
+include::painless-contexts/index.asciidoc[]

docs/painless/painless-contexts/index.asciidoc

@@ -0,0 +1,35 @@
+include::painless-update-context.asciidoc[]
+
+include::painless-update-by-query-context.asciidoc[]
+
+include::painless-reindex-context.asciidoc[]
+
+include::painless-sort-context.asciidoc[]
+
+include::painless-similarity-context.asciidoc[]
+
+include::painless-weight-context.asciidoc[]
+
+include::painless-score-context.asciidoc[]
+
+include::painless-field-context.asciidoc[]
+
+include::painless-filter-context.asciidoc[]
+
+include::painless-min-should-match-context.asciidoc[]
+
+include::painless-metric-agg-init-context.asciidoc[]
+
+include::painless-metric-agg-map-context.asciidoc[]
+
+include::painless-metric-agg-combine-context.asciidoc[]
+
+include::painless-metric-agg-reduce-context.asciidoc[]
+
+include::painless-bucket-agg-context.asciidoc[]
+
+include::painless-ingest-processor-context.asciidoc[]
+
+include::painless-watcher-condition-context.asciidoc[]
+
+include::painless-watcher-transform-context.asciidoc[]

docs/painless/painless-contexts/painless-bucket-agg-context.asciidoc

@@ -0,0 +1,21 @@
+[[painless-bucket-agg-context]]
+=== Bucket aggregation context
+
+Use a Painless script in an
+{es_version}/search-aggregations-pipeline-bucket-script-aggregation.html[bucket aggregation]
+to calculate a value as a result in a bucket.
+
+*Variables*
+
+`params` (`Map`, read-only)::
+        User-defined parameters passed in as part of the query. The parameters
+        include values defined as part of the `buckets_path`.
+
+*Return*
+
+numeric::
+        The calculated value as the result.
+
+*API*
+
+The standard <<painless-api-reference, Painless API>> is available.

docs/painless/painless-contexts/painless-field-context.asciidoc

@@ -0,0 +1,31 @@
+[[painless-field-context]]
+=== Field context
+
+Use a Painless script to create a
+{es_version}/search-request-script-fields.html[script field] to return
+a customized value for each document in the results of a query.
+
+*Variables*
+
+`params` (`Map`, read-only)::
+        User-defined parameters passed in as part of the query.
+
+`doc` (`Map`, read-only)::
+        Contains the fields of the specified document where each field is a
+        `List` of values.
+
+{es_version}/mapping-source-field.html[`ctx['_source']`] (`Map`)::
+        Contains extracted JSON in a `Map` and `List` structure for the fields
+        existing in a stored document.
+
+`_score` (`double` read-only)::
+        The original score of the specified document.
+
+*Return*
+
+`Object`::
+        The customized value for each document.
+
+*API*
+
+The standard <<painless-api-reference, Painless API>> is available.

docs/painless/painless-contexts/painless-filter-context.asciidoc

@@ -0,0 +1,26 @@
+[[painless-filter-context]]
+=== Filter context
+
+Use a Painless script as a {es_version}/query-dsl-script-query.html[filter] in a
+query to include and exclude documents.
+
+
+*Variables*
+
+`params` (`Map`, read-only)::
+        User-defined parameters passed in as part of the query.
+
+`doc` (`Map`, read-only)::
+        Contains the fields of the current document where each field is a
+        `List` of values.
+
+*Return*
+
+`boolean`::
+        Return `true` if the current document should be returned as a result of
+        the query, and `false` otherwise.
+
+
+*API*
+
+The standard <<painless-api-reference, Painless API>> is available.

docs/painless/painless-contexts/painless-ingest-processor-context.asciidoc

@@ -0,0 +1,41 @@
+[[painless-ingest-processor-context]]
+=== Ingest processor context
+
+Use a Painless script in an {es_version}/script-processor.html[ingest processor]
+to modify documents upon insertion.
+
+*Variables*
+
+`params` (`Map`, read-only)::
+        User-defined parameters passed in as part of the query.
+
+{es_version}/mapping-index-field.html[`ctx['_index']`] (`String`)::
+        The name of the index.
+
+{es_version}/mapping-type-field.html[`ctx['_type']`] (`String`)::
+        The type of document within an index.
+
+`ctx` (`Map`)::
+        Contains extracted JSON in a `Map` and `List` structure for the fields
+        that are part of the document.
+
+*Side Effects*
+
+{es_version}/mapping-index-field.html[`ctx['_index']`]::
+        Modify this to change the destination index for the current document.
+
+{es_version}/mapping-type-field.html[`ctx['_type']`]::
+        Modify this to change the type for the current document.
+
+`ctx` (`Map`, read-only)::
+        Modify the values in the `Map/List` structure to add, modify, or delete
+        the fields of a document.
+
+*Return*
+
+void::
+        No expected return value.
+
+*API*
+
+The standard <<painless-api-reference, Painless API>> is available.

docs/painless/painless-contexts/painless-metric-agg-combine-context.asciidoc

@@ -0,0 +1,27 @@
+[[painless-metric-agg-combine-context]]
+=== Metric aggregation combine context
+
+Use a Painless script to
+{es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[combine]
+values for use in a scripted metric aggregation. A combine script is run once
+per shard following a <<painless-metric-agg-map-context, map script>> and is
+optional as part of a full metric aggregation.
+
+*Variables*
+
+`params` (`Map`, read-only)::
+        User-defined parameters passed in as part of the query.
+
+`params['_agg']` (`Map`)::
+        `Map` with values available from the prior map script.
+
+*Return*
+
+`List`, `Map`, `String`, or primitive::
+        A value collected for use in a
+        <<painless-metric-agg-reduce-context, reduce script>>. If no reduce
+        script is specified, the value is used as part of the result.
+
+*API*
+
+The standard <<painless-api-reference, Painless API>> is available.

docs/painless/painless-contexts/painless-metric-agg-init-context.asciidoc

@@ -0,0 +1,32 @@
+[[painless-metric-agg-init-context]]
+=== Metric aggregation initialization context
+
+Use a Painless script to
+{es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[initialize]
+values for use in a scripted metric aggregation. An initialization script is
+run prior to document collection once per shard and is optional as part of the
+full metric aggregation.
+
+*Variables*
+
+`params` (`Map`, read-only)::
+        User-defined parameters passed in as part of the query.
+
+`params['_agg']` (`Map`)::
+        Empty `Map` used to add values for use in a
+        <<painless-metric-agg-map-context, map script>>.
+
+*Side Effects*
+
+`params['_agg']` (`Map`)::
+        Add values to this `Map` to for use in a map.  Additional values must
+        be of the type `Map`, `List`, `String` or primitive.
+
+*Return*
+
+`void`::
+        No expected return value.
+
+*API*
+
+The standard <<painless-api-reference, Painless API>> is available.

docs/painless/painless-contexts/painless-metric-agg-map-context.asciidoc

@@ -0,0 +1,47 @@
+[[painless-metric-agg-map-context]]
+=== Metric aggregation map context
+
+Use a Painless script to
+{es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[map]
+values for use in a scripted metric aggregation. A map script is run once per
+collected document following an optional
+<<painless-metric-agg-init-context, initialization script>> and is required as
+part of a full metric aggregation.
+
+*Variables*
+
+`params` (`Map`, read-only)::
+        User-defined parameters passed in as part of the query.
+
+`params['_agg']` (`Map`)::
+        `Map` used to add values for processing in a
+        <<painless-metric-agg-map-context, combine script>> or returned
+        directly.
+
+`doc` (`Map`, read-only)::
+        Contains the fields of the current document where each field is a
+        `List` of values.
+
+`_score` (`double` read-only)::
+        The similarity score of the current document.
+
+*Side Effects*
+
+`params['_agg']` (`Map`)::
+        Use this `Map` to add values for processing in a combine script.
+        Additional values must be of the type `Map`, `List`, `String` or
+        primitive. If an initialization script is provided as part the
+        aggregation then values added from the initialization script are
+        available as well.  If no combine script is specified, values must be
+        directly stored in `_agg`. If no combine script and no
+        <<painless-metric-agg-reduce-context, reduce script>> are specified, the
+        values are used as the result.
+
+*Return*
+
+`void`::
+        No expected return value.
+
+*API*
+
+The standard <<painless-api-reference, Painless API>> is available.

docs/painless/painless-contexts/painless-metric-agg-reduce-context.asciidoc

@@ -0,0 +1,28 @@
+[[painless-metric-agg-reduce-context]]
+=== Metric aggregation reduce context
+
+Use a Painless script to
+{es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[reduce]
+values to produce the result of a scripted metric aggregation. A reduce script
+is run once on the coordinating node following a
+<<painless-metric-agg-combine-context, combine script>> (or a
+<<painless-metric-agg-map-context, map script>> if no combine script is
+specified) and is optional as part of a full metric aggregation.
+
+*Variables*
+
+`params` (`Map`, read-only)::
+        User-defined parameters passed in as part of the query.
+
+`params['_aggs']` (`Map`)::
+        `Map` with values available from the prior combine script (or a map
+        script if no combine script is specified).
+
+*Return*
+
+`List`, `Map`, `String`, or primitive::
+        A value used as the result.
+
+*API*
+
+The standard <<painless-api-reference, Painless API>> is available.

docs/painless/painless-contexts/painless-min-should-match-context.asciidoc

@@ -0,0 +1,28 @@
+[[painless-min-should-match-context]]
+=== Minimum should match context
+
+Use a Painless script to specify the
+{es_version}/query-dsl-terms-set-query.html[minimum] number of terms that a
+specified field needs to match with for a document to be part of the query
+results.
+
+*Variables*
+
+`params` (`Map`, read-only)::
+        User-defined parameters passed in as part of the query.
+
+`params['num_terms']` (`int`, read-only)::
+        The number of terms specified to match with.
+
+`doc` (`Map`, read-only)::
+        Contains the fields of the current document where each field is a
+        `List` of values.
+
+*Return*
+
+`int`::
+        The minimum number of terms required to match the current document.
+
+*API*
+
+The standard <<painless-api-reference, Painless API>> is available.