Skip to content

Commit 631a53a

Browse files
jdconradjdconrad
authored
Painless: Add Context Docs (#31190)
Adds documentation for each the variables and API available with each script context usable with a Painless script.
1 parent 8f2feb8 commit 631a53a

23 files changed

+781
-3
lines changed

‎docs/painless/index.asciidoc

+3-1
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,6 @@ include::painless-getting-started.asciidoc[]
77

88
include::painless-lang-spec.asciidoc[]
99

10-
include::painless-api-reference.asciidoc[]
10+
include::painless-contexts.asciidoc[]
11+
12+
include::painless-api-reference.asciidoc[]

‎docs/painless/painless-contexts.asciidoc

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
[[painless-contexts]]
2+
== Painless contexts
3+
4+
:es_version: https://www.elastic.co/guide/en/elasticsearch/reference/master
5+
:xp_version: https://www.elastic.co/guide/en/x-pack/current
6+
7+
A Painless script is evaluated within a context. Each context has values that
8+
are available as local variables, a whitelist that controls the available
9+
classes, and the methods and fields within those classes (API), and
10+
if and what type of value is returned.
11+
12+
A Painless script is typically executed within one of the contexts in the table
13+
below. Note this is not necessarily a comprehensive list as custom plugins and
14+
specialized code may define new ways to use a Painless script.
15+
16+
[options="header",cols="<1,<1,<1"]
17+
|====
18+
| Name | Painless Documentation
19+
| Elasticsearch Documentation
20+
| Update | <<painless-update-context, Painless Documentation>>
21+
| {es_version}/docs-update.html[Elasticsearch Documentation]
22+
| Update by query | <<painless-update-by-query-context, Painless Documentation>>
23+
| {es_version}/docs-update-by-query.html[Elasticsearch Documentation]
24+
| Reindex | <<painless-reindex-context, Painless Documentation>>
25+
| {es_version}/docs-reindex.html[Elasticsearch Documentation]
26+
| Sort | <<painless-sort-context, Painless Documentation>>
27+
| {es_version}/search-request-sort.html[Elasticsearch Documentation]
28+
| Similarity | <<painless-similarity-context, Painless Documentation>>
29+
| {es_version}/index-modules-similarity.html[Elasticsearch Documentation]
30+
| Weight | <<painless-similarity-context, Painless Documentation>>
31+
| {es_version}/index-modules-similarity.html[Elasticsearch Documentation]
32+
| Score | <<painless-score-context, Painless Documentation>>
33+
| {es_version}/query-dsl-function-score-query.html[Elasticsearch Documentation]
34+
| Field | <<painless-field-context, Painless Documentation>>
35+
| {es_version}/search-request-script-fields.html[Elasticsearch Documentation]
36+
| Filter | <<painless-filter-context, Painless Documentation>>
37+
| {es_version}/query-dsl-script-query.html[Elasticsearch Documentation]
38+
| Minimum should match | <<painless-min-should-match-context, Painless Documentation>>
39+
| {es_version}/query-dsl-terms-set-query.html[Elasticsearch Documentation]
40+
| Metric aggregation initialization | <<painless-metric-agg-init-context, Painless Documentation>>
41+
| {es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation]
42+
| Metric aggregation map | <<painless-metric-agg-map-context, Painless Documentation>>
43+
| {es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation]
44+
| Metric aggregation combine | <<painless-metric-agg-combine-context, Painless Documentation>>
45+
| {es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation]
46+
| Metric aggregation reduce | <<painless-metric-agg-reduce-context, Painless Documentation>>
47+
| {es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation]
48+
| Bucket aggregation | <<painless-bucket-agg-context, Painless Documentation>>
49+
| {es_version}/search-aggregations-pipeline-bucket-script-aggregation.html[Elasticsearch Documentation]
50+
| Ingest processor | <<painless-ingest-processor-context, Painless Documentation>>
51+
| {es_version}/script-processor.html[Elasticsearch Documentation]
52+
| Watcher condition | <<painless-watcher-condition-context, Painless Documentation>>
53+
| {xp_version}/condition-script.html[Elasticsearch Documentation]
54+
| Watcher transform | <<painless-watcher-transform-context, Painless Documentation>>
55+
| {xp_version}/transform-script.html[Elasticsearch Documentation]
56+
|====
57+
58+
include::painless-contexts/index.asciidoc[]

‎docs/painless/painless-contexts/index.asciidoc

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
include::painless-update-context.asciidoc[]
2+
3+
include::painless-update-by-query-context.asciidoc[]
4+
5+
include::painless-reindex-context.asciidoc[]
6+
7+
include::painless-sort-context.asciidoc[]
8+
9+
include::painless-similarity-context.asciidoc[]
10+
11+
include::painless-weight-context.asciidoc[]
12+
13+
include::painless-score-context.asciidoc[]
14+
15+
include::painless-field-context.asciidoc[]
16+
17+
include::painless-filter-context.asciidoc[]
18+
19+
include::painless-min-should-match-context.asciidoc[]
20+
21+
include::painless-metric-agg-init-context.asciidoc[]
22+
23+
include::painless-metric-agg-map-context.asciidoc[]
24+
25+
include::painless-metric-agg-combine-context.asciidoc[]
26+
27+
include::painless-metric-agg-reduce-context.asciidoc[]
28+
29+
include::painless-bucket-agg-context.asciidoc[]
30+
31+
include::painless-ingest-processor-context.asciidoc[]
32+
33+
include::painless-watcher-condition-context.asciidoc[]
34+
35+
include::painless-watcher-transform-context.asciidoc[]

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

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
[[painless-bucket-agg-context]]
2+
=== Bucket aggregation context
3+
4+
Use a Painless script in an
5+
{es_version}/search-aggregations-pipeline-bucket-script-aggregation.html[bucket aggregation]
6+
to calculate a value as a result in a bucket.
7+
8+
*Variables*
9+
10+
`params` (`Map`, read-only)::
11+
User-defined parameters passed in as part of the query. The parameters
12+
include values defined as part of the `buckets_path`.
13+
14+
*Return*
15+
16+
numeric::
17+
The calculated value as the result.
18+
19+
*API*
20+
21+
The standard <<painless-api-reference, Painless API>> is available.

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

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
[[painless-field-context]]
2+
=== Field context
3+
4+
Use a Painless script to create a
5+
{es_version}/search-request-script-fields.html[script field] to return
6+
a customized value for each document in the results of a query.
7+
8+
*Variables*
9+
10+
`params` (`Map`, read-only)::
11+
User-defined parameters passed in as part of the query.
12+
13+
`doc` (`Map`, read-only)::
14+
Contains the fields of the specified document where each field is a
15+
`List` of values.
16+
17+
{es_version}/mapping-source-field.html[`ctx['_source']`] (`Map`)::
18+
Contains extracted JSON in a `Map` and `List` structure for the fields
19+
existing in a stored document.
20+
21+
`_score` (`double` read-only)::
22+
The original score of the specified document.
23+
24+
*Return*
25+
26+
`Object`::
27+
The customized value for each document.
28+
29+
*API*
30+
31+
The standard <<painless-api-reference, Painless API>> is available.

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

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
[[painless-filter-context]]
2+
=== Filter context
3+
4+
Use a Painless script as a {es_version}/query-dsl-script-query.html[filter] in a
5+
query to include and exclude documents.
6+
7+
8+
*Variables*
9+
10+
`params` (`Map`, read-only)::
11+
User-defined parameters passed in as part of the query.
12+
13+
`doc` (`Map`, read-only)::
14+
Contains the fields of the current document where each field is a
15+
`List` of values.
16+
17+
*Return*
18+
19+
`boolean`::
20+
Return `true` if the current document should be returned as a result of
21+
the query, and `false` otherwise.
22+
23+
24+
*API*
25+
26+
The standard <<painless-api-reference, Painless API>> is available.

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

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
[[painless-ingest-processor-context]]
2+
=== Ingest processor context
3+
4+
Use a Painless script in an {es_version}/script-processor.html[ingest processor]
5+
to modify documents upon insertion.
6+
7+
*Variables*
8+
9+
`params` (`Map`, read-only)::
10+
User-defined parameters passed in as part of the query.
11+
12+
{es_version}/mapping-index-field.html[`ctx['_index']`] (`String`)::
13+
The name of the index.
14+
15+
{es_version}/mapping-type-field.html[`ctx['_type']`] (`String`)::
16+
The type of document within an index.
17+
18+
`ctx` (`Map`)::
19+
Contains extracted JSON in a `Map` and `List` structure for the fields
20+
that are part of the document.
21+
22+
*Side Effects*
23+
24+
{es_version}/mapping-index-field.html[`ctx['_index']`]::
25+
Modify this to change the destination index for the current document.
26+
27+
{es_version}/mapping-type-field.html[`ctx['_type']`]::
28+
Modify this to change the type for the current document.
29+
30+
`ctx` (`Map`, read-only)::
31+
Modify the values in the `Map/List` structure to add, modify, or delete
32+
the fields of a document.
33+
34+
*Return*
35+
36+
void::
37+
No expected return value.
38+
39+
*API*
40+
41+
The standard <<painless-api-reference, Painless API>> is available.

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

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[[painless-metric-agg-combine-context]]
2+
=== Metric aggregation combine context
3+
4+
Use a Painless script to
5+
{es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[combine]
6+
values for use in a scripted metric aggregation. A combine script is run once
7+
per shard following a <<painless-metric-agg-map-context, map script>> and is
8+
optional as part of a full metric aggregation.
9+
10+
*Variables*
11+
12+
`params` (`Map`, read-only)::
13+
User-defined parameters passed in as part of the query.
14+
15+
`params['_agg']` (`Map`)::
16+
`Map` with values available from the prior map script.
17+
18+
*Return*
19+
20+
`List`, `Map`, `String`, or primitive::
21+
A value collected for use in a
22+
<<painless-metric-agg-reduce-context, reduce script>>. If no reduce
23+
script is specified, the value is used as part of the result.
24+
25+
*API*
26+
27+
The standard <<painless-api-reference, Painless API>> is available.

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

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
[[painless-metric-agg-init-context]]
2+
=== Metric aggregation initialization context
3+
4+
Use a Painless script to
5+
{es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[initialize]
6+
values for use in a scripted metric aggregation. An initialization script is
7+
run prior to document collection once per shard and is optional as part of the
8+
full metric aggregation.
9+
10+
*Variables*
11+
12+
`params` (`Map`, read-only)::
13+
User-defined parameters passed in as part of the query.
14+
15+
`params['_agg']` (`Map`)::
16+
Empty `Map` used to add values for use in a
17+
<<painless-metric-agg-map-context, map script>>.
18+
19+
*Side Effects*
20+
21+
`params['_agg']` (`Map`)::
22+
Add values to this `Map` to for use in a map. Additional values must
23+
be of the type `Map`, `List`, `String` or primitive.
24+
25+
*Return*
26+
27+
`void`::
28+
No expected return value.
29+
30+
*API*
31+
32+
The standard <<painless-api-reference, Painless API>> is available.

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

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
[[painless-metric-agg-map-context]]
2+
=== Metric aggregation map context
3+
4+
Use a Painless script to
5+
{es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[map]
6+
values for use in a scripted metric aggregation. A map script is run once per
7+
collected document following an optional
8+
<<painless-metric-agg-init-context, initialization script>> and is required as
9+
part of a full metric aggregation.
10+
11+
*Variables*
12+
13+
`params` (`Map`, read-only)::
14+
User-defined parameters passed in as part of the query.
15+
16+
`params['_agg']` (`Map`)::
17+
`Map` used to add values for processing in a
18+
<<painless-metric-agg-map-context, combine script>> or returned
19+
directly.
20+
21+
`doc` (`Map`, read-only)::
22+
Contains the fields of the current document where each field is a
23+
`List` of values.
24+
25+
`_score` (`double` read-only)::
26+
The similarity score of the current document.
27+
28+
*Side Effects*
29+
30+
`params['_agg']` (`Map`)::
31+
Use this `Map` to add values for processing in a combine script.
32+
Additional values must be of the type `Map`, `List`, `String` or
33+
primitive. If an initialization script is provided as part the
34+
aggregation then values added from the initialization script are
35+
available as well. If no combine script is specified, values must be
36+
directly stored in `_agg`. If no combine script and no
37+
<<painless-metric-agg-reduce-context, reduce script>> are specified, the
38+
values are used as the result.
39+
40+
*Return*
41+
42+
`void`::
43+
No expected return value.
44+
45+
*API*
46+
47+
The standard <<painless-api-reference, Painless API>> is available.

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

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
[[painless-metric-agg-reduce-context]]
2+
=== Metric aggregation reduce context
3+
4+
Use a Painless script to
5+
{es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[reduce]
6+
values to produce the result of a scripted metric aggregation. A reduce script
7+
is run once on the coordinating node following a
8+
<<painless-metric-agg-combine-context, combine script>> (or a
9+
<<painless-metric-agg-map-context, map script>> if no combine script is
10+
specified) and is optional as part of a full metric aggregation.
11+
12+
*Variables*
13+
14+
`params` (`Map`, read-only)::
15+
User-defined parameters passed in as part of the query.
16+
17+
`params['_aggs']` (`Map`)::
18+
`Map` with values available from the prior combine script (or a map
19+
script if no combine script is specified).
20+
21+
*Return*
22+
23+
`List`, `Map`, `String`, or primitive::
24+
A value used as the result.
25+
26+
*API*
27+
28+
The standard <<painless-api-reference, Painless API>> is available.

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

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
[[painless-min-should-match-context]]
2+
=== Minimum should match context
3+
4+
Use a Painless script to specify the
5+
{es_version}/query-dsl-terms-set-query.html[minimum] number of terms that a
6+
specified field needs to match with for a document to be part of the query
7+
results.
8+
9+
*Variables*
10+
11+
`params` (`Map`, read-only)::
12+
User-defined parameters passed in as part of the query.
13+
14+
`params['num_terms']` (`int`, read-only)::
15+
The number of terms specified to match with.
16+
17+
`doc` (`Map`, read-only)::
18+
Contains the fields of the current document where each field is a
19+
`List` of values.
20+
21+
*Return*
22+
23+
`int`::
24+
The minimum number of terms required to match the current document.
25+
26+
*API*
27+
28+
The standard <<painless-api-reference, Painless API>> is available.

0 commit comments

Comments
 (0)