From 631a53a0e1d6be928f6c7bb55bc4c64de5bba695 Mon Sep 17 00:00:00 2001 From: Jack Conradson Date: Mon, 2 Jul 2018 14:44:36 -0700 Subject: [PATCH] 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 | 4 +- docs/painless/painless-contexts.asciidoc | 58 ++++++++++++++++ .../painless/painless-contexts/index.asciidoc | 35 ++++++++++ .../painless-bucket-agg-context.asciidoc | 21 ++++++ .../painless-field-context.asciidoc | 31 +++++++++ .../painless-filter-context.asciidoc | 26 +++++++ ...painless-ingest-processor-context.asciidoc | 41 +++++++++++ ...inless-metric-agg-combine-context.asciidoc | 27 ++++++++ .../painless-metric-agg-init-context.asciidoc | 32 +++++++++ .../painless-metric-agg-map-context.asciidoc | 47 +++++++++++++ ...ainless-metric-agg-reduce-context.asciidoc | 28 ++++++++ ...painless-min-should-match-context.asciidoc | 28 ++++++++ .../painless-reindex-context.asciidoc | 68 +++++++++++++++++++ .../painless-score-context.asciidoc | 27 ++++++++ .../painless-similarity-context.asciidoc | 53 +++++++++++++++ .../painless-sort-context.asciidoc | 26 +++++++ .../painless-update-by-query-context.asciidoc | 54 +++++++++++++++ .../painless-update-context.asciidoc | 55 +++++++++++++++ ...ainless-watcher-condition-context.asciidoc | 38 +++++++++++ ...ainless-watcher-transform-context.asciidoc | 39 +++++++++++ .../painless-weight-context.asciidoc | 42 ++++++++++++ .../painless-operators-array.asciidoc | 2 +- docs/painless/painless-scripts.asciidoc | 2 +- 23 files changed, 781 insertions(+), 3 deletions(-) create mode 100644 docs/painless/painless-contexts.asciidoc create mode 100644 docs/painless/painless-contexts/index.asciidoc create mode 100644 docs/painless/painless-contexts/painless-bucket-agg-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-field-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-filter-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-ingest-processor-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-metric-agg-combine-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-metric-agg-init-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-metric-agg-map-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-metric-agg-reduce-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-min-should-match-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-reindex-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-score-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-similarity-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-sort-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-update-by-query-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-update-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-watcher-condition-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-watcher-transform-context.asciidoc create mode 100644 docs/painless/painless-contexts/painless-weight-context.asciidoc diff --git a/docs/painless/index.asciidoc b/docs/painless/index.asciidoc index abfd4d4f00a..92e0a33bf13 100644 --- a/docs/painless/index.asciidoc +++ b/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[] \ No newline at end of file diff --git a/docs/painless/painless-contexts.asciidoc b/docs/painless/painless-contexts.asciidoc new file mode 100644 index 00000000000..ff46f6bd74d --- /dev/null +++ b/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 | <> + | {es_version}/docs-update.html[Elasticsearch Documentation] +| Update by query | <> + | {es_version}/docs-update-by-query.html[Elasticsearch Documentation] +| Reindex | <> + | {es_version}/docs-reindex.html[Elasticsearch Documentation] +| Sort | <> + | {es_version}/search-request-sort.html[Elasticsearch Documentation] +| Similarity | <> + | {es_version}/index-modules-similarity.html[Elasticsearch Documentation] +| Weight | <> + | {es_version}/index-modules-similarity.html[Elasticsearch Documentation] +| Score | <> + | {es_version}/query-dsl-function-score-query.html[Elasticsearch Documentation] +| Field | <> + | {es_version}/search-request-script-fields.html[Elasticsearch Documentation] +| Filter | <> + | {es_version}/query-dsl-script-query.html[Elasticsearch Documentation] +| Minimum should match | <> + | {es_version}/query-dsl-terms-set-query.html[Elasticsearch Documentation] +| Metric aggregation initialization | <> + | {es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation] +| Metric aggregation map | <> + | {es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation] +| Metric aggregation combine | <> + | {es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation] +| Metric aggregation reduce | <> + | {es_version}/search-aggregations-metrics-scripted-metric-aggregation.html[Elasticsearch Documentation] +| Bucket aggregation | <> + | {es_version}/search-aggregations-pipeline-bucket-script-aggregation.html[Elasticsearch Documentation] +| Ingest processor | <> + | {es_version}/script-processor.html[Elasticsearch Documentation] +| Watcher condition | <> + | {xp_version}/condition-script.html[Elasticsearch Documentation] +| Watcher transform | <> + | {xp_version}/transform-script.html[Elasticsearch Documentation] +|==== + +include::painless-contexts/index.asciidoc[] diff --git a/docs/painless/painless-contexts/index.asciidoc b/docs/painless/painless-contexts/index.asciidoc new file mode 100644 index 00000000000..64e4326e052 --- /dev/null +++ b/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[] diff --git a/docs/painless/painless-contexts/painless-bucket-agg-context.asciidoc b/docs/painless/painless-contexts/painless-bucket-agg-context.asciidoc new file mode 100644 index 00000000000..b277055d87d --- /dev/null +++ b/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 <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-field-context.asciidoc b/docs/painless/painless-contexts/painless-field-context.asciidoc new file mode 100644 index 00000000000..bf44703001b --- /dev/null +++ b/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 <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-filter-context.asciidoc b/docs/painless/painless-contexts/painless-filter-context.asciidoc new file mode 100644 index 00000000000..ea0393893c8 --- /dev/null +++ b/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 <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-ingest-processor-context.asciidoc b/docs/painless/painless-contexts/painless-ingest-processor-context.asciidoc new file mode 100644 index 00000000000..ba3be073963 --- /dev/null +++ b/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 <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-metric-agg-combine-context.asciidoc b/docs/painless/painless-contexts/painless-metric-agg-combine-context.asciidoc new file mode 100644 index 00000000000..1fec63ef446 --- /dev/null +++ b/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 <> 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 + <>. If no reduce + script is specified, the value is used as part of the result. + +*API* + +The standard <> is available. diff --git a/docs/painless/painless-contexts/painless-metric-agg-init-context.asciidoc b/docs/painless/painless-contexts/painless-metric-agg-init-context.asciidoc new file mode 100644 index 00000000000..ed7e01ddd00 --- /dev/null +++ b/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 + <>. + +*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 <> is available. diff --git a/docs/painless/painless-contexts/painless-metric-agg-map-context.asciidoc b/docs/painless/painless-contexts/painless-metric-agg-map-context.asciidoc new file mode 100644 index 00000000000..51f06e010db --- /dev/null +++ b/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 +<> 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 + <> 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 + <> are specified, the + values are used as the result. + +*Return* + +`void`:: + No expected return value. + +*API* + +The standard <> is available. diff --git a/docs/painless/painless-contexts/painless-metric-agg-reduce-context.asciidoc b/docs/painless/painless-contexts/painless-metric-agg-reduce-context.asciidoc new file mode 100644 index 00000000000..1b64b85392d --- /dev/null +++ b/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 +<> (or a +<> 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 <> is available. diff --git a/docs/painless/painless-contexts/painless-min-should-match-context.asciidoc b/docs/painless/painless-contexts/painless-min-should-match-context.asciidoc new file mode 100644 index 00000000000..c310f42928e --- /dev/null +++ b/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 <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-reindex-context.asciidoc b/docs/painless/painless-contexts/painless-reindex-context.asciidoc new file mode 100644 index 00000000000..a8477c8c619 --- /dev/null +++ b/docs/painless/painless-contexts/painless-reindex-context.asciidoc @@ -0,0 +1,68 @@ +[[painless-reindex-context]] +=== Reindex context + +Use a Painless script in a {es_version}/docs-reindex.html[reindex] operation to +add, modify, or delete fields within each document in an original index as its +reindexed into a target index. + +*Variables* + +`params` (`Map`, read-only):: + User-defined parameters passed in as part of the query. + +`ctx['_op']` (`String`):: + The name of the operation. + +{es_version}/mapping-routing-field.html[`ctx['_routing']`] (`String`):: + The value used to select a shard for document storage. + +{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. + +{es_version}/mapping-id-field.html[`ctx['_id']`] (`int`, read-only):: + The unique document id. + +`ctx['_version']` (`int`):: + The current version of the document. + +{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. + +*Side Effects* + +`ctx['_op']`:: + Use the default of `index` to update a document. Set to `none` to + specify no operation or `delete` to delete the current document from + the index. + +{es_version}/mapping-routing-field.html[`ctx['_routing']`]:: + Modify this to change the routing value for the current document. + +{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. + +{es_version}/mapping-id-field.html[`ctx['_id']`]:: + Modify this to change the id for the current document. + +`ctx['_version']` (`int`):: + Modify this to modify the version for the current document. + +{es_version}/mapping-source-field.html[`ctx['_source']`]:: + 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 <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-score-context.asciidoc b/docs/painless/painless-contexts/painless-score-context.asciidoc new file mode 100644 index 00000000000..21667fd31f3 --- /dev/null +++ b/docs/painless/painless-contexts/painless-score-context.asciidoc @@ -0,0 +1,27 @@ +[[painless-score-context]] +=== Score context + +Use a Painless script in a +{es_version}/query-dsl-function-score-query.html[function score] to apply a new +score to documents returned from 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 current document where each field is a + `List` of values. + +`_score` (`double` read-only):: + The similarity score of the current document. + +*Return* + +`double`:: + The score for the current document. + +*API* + +The standard <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-similarity-context.asciidoc b/docs/painless/painless-contexts/painless-similarity-context.asciidoc new file mode 100644 index 00000000000..052844c3111 --- /dev/null +++ b/docs/painless/painless-contexts/painless-similarity-context.asciidoc @@ -0,0 +1,53 @@ +[[painless-similarity-context]] +=== Similarity context + +Use a Painless script to create a +{es_version}/index-modules-similarity.html[similarity] equation for scoring +documents in a query. + +*Variables* + +`params` (`Map`, read-only):: + User-defined parameters passed in as part of the query. + +*Variables* + +`params` (`Map`, read-only):: + User-defined parameters passed in at query-time. + +`query.boost` (`float`, read-only):: + The boost value if provided by the query. If this is not provided the + value is `1.0f`. + +`field.docCount` (`long`, read-only):: + The number of documents that have a value for the current field. + +`field.sumDocFreq` (`long`, read-only):: + The sum of all terms that exist for the current field. If this is not + available the value is `-1`. + +`field.sumTotalTermFreq` (`long`, read-only):: + The sum of occurrences in the index for all the terms that exist in the + current field. If this is not available the value is `-1`. + +`term.docFreq` (`long`, read-only):: + The number of documents that contain the current term in the index. + +`term.totalTermFreq` (`long`, read-only):: + The total occurrences of the current term in the index. + +`doc.length` (`long`, read-only):: + The number of tokens the current document has in the current field. + +`doc.freq` (`long`, read-only):: + The number of occurrences of the current term in the current + document for the current field. + +*Return* + +`double`:: + The similarity score for the current document. + +*API* + +The standard <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-sort-context.asciidoc b/docs/painless/painless-contexts/painless-sort-context.asciidoc new file mode 100644 index 00000000000..7f510fb6a92 --- /dev/null +++ b/docs/painless/painless-contexts/painless-sort-context.asciidoc @@ -0,0 +1,26 @@ +[[painless-sort-context]] +=== Sort context + +Use a Painless script to +{es_version}/search-request-sort.html[sort] the documents in 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 current document where each field is a + `List` of values. + +`_score` (`double` read-only):: + The similarity score of the current document. + +*Return* + +`double`:: + The score for the specified document. + +*API* + +The standard <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-update-by-query-context.asciidoc b/docs/painless/painless-contexts/painless-update-by-query-context.asciidoc new file mode 100644 index 00000000000..65666e15844 --- /dev/null +++ b/docs/painless/painless-contexts/painless-update-by-query-context.asciidoc @@ -0,0 +1,54 @@ +[[painless-update-by-query-context]] +=== Update by query context + +Use a Painless script in an +{es_version}/docs-update-by-query.html[update by query] operation to add, +modify, or delete fields within each of a set of documents collected as the +result of query. + +*Variables* + +`params` (`Map`, read-only):: + User-defined parameters passed in as part of the query. + +`ctx['_op']` (`String`):: + The name of the operation. + +{es_version}/mapping-routing-field.html[`ctx['_routing']`] (`String`, read-only):: + The value used to select a shard for document storage. + +{es_version}/mapping-index-field.html[`ctx['_index']`] (`String`, read-only):: + The name of the index. + +{es_version}/mapping-type-field.html[`ctx['_type']`] (`String`, read-only):: + The type of document within an index. + +{es_version}/mapping-id-field.html[`ctx['_id']`] (`int`, read-only):: + The unique document id. + +`ctx['_version']` (`int`, read-only):: + The current version of the document. + +{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. + +*Side Effects* + +`ctx['_op']`:: + Use the default of `index` to update a document. Set to `none` to + specify no operation or `delete` to delete the current document from + the index. + +{es_version}/mapping-source-field.html[`ctx['_source']`]:: + 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 <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-update-context.asciidoc b/docs/painless/painless-contexts/painless-update-context.asciidoc new file mode 100644 index 00000000000..b04ba8d9ffb --- /dev/null +++ b/docs/painless/painless-contexts/painless-update-context.asciidoc @@ -0,0 +1,55 @@ +[[painless-update-context]] +=== Update context + +Use a Painless script in an {es_version}/docs-update.html[update] operation to +add, modify, or delete fields within a single document. + +*Variables* + +`params` (`Map`, read-only):: + User-defined parameters passed in as part of the query. + +`ctx['_op']` (`String`):: + The name of the operation. + +{es_version}/mapping-routing-field.html[`ctx['_routing']`] (`String`, read-only):: + The value used to select a shard for document storage. + +{es_version}/mapping-index-field.html[`ctx['_index']`] (`String`, read-only):: + The name of the index. + +{es_version}/mapping-type-field.html[`ctx['_type']`] (`String`, read-only):: + The type of document within an index. + +{es_version}/mapping-id-field.html[`ctx['_id']`] (`int`, read-only):: + The unique document id. + +`ctx['_version']` (`int`, read-only):: + The current version of the document. + +`ctx['_now']` (`long`, read-only):: + The current timestamp in milliseconds. + +{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. + +*Side Effects* + +`ctx['_op']`:: + Use the default of `index` to update a document. Set to `none` to + specify no operation or `delete` to delete the current document from + the index. + +{es_version}/mapping-source-field.html[`ctx['_source']`]:: + 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 <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-watcher-condition-context.asciidoc b/docs/painless/painless-contexts/painless-watcher-condition-context.asciidoc new file mode 100644 index 00000000000..3a5e460a55d --- /dev/null +++ b/docs/painless/painless-contexts/painless-watcher-condition-context.asciidoc @@ -0,0 +1,38 @@ +[[painless-watcher-condition-context]] +=== Watcher condition context + +Use a Painless script as a {xp_version}/condition-script.html[watcher condition] +to test if a response is necessary. + +*Variables* + +`params` (`Map`, read-only):: + User-defined parameters passed in as part of the query. + +`ctx['watch_id']` (`String`, read-only):: + The id of the watch. + +`ctx['execution_time']` (`DateTime`, read-only):: + The start time for the watch. + +`ctx['trigger']['scheduled_time']` (`DateTime`, read-only):: + The scheduled trigger time for the watch. + +`ctx['trigger']['triggered_time']` (`DateTime`, read-only):: + The actual trigger time for the watch. + +`ctx['metadata']` (`Map`, read-only):: + Any metadata associated with the watch. + +`ctx['payload']` (`Map`, read-only):: + The accessible watch data based upon the + {xp_version}/input.html[watch input]. + +*Return* + +`boolean`:: + Expects `true` if the condition is met, and `false` otherwise. + +*API* + +The standard <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-watcher-transform-context.asciidoc b/docs/painless/painless-contexts/painless-watcher-transform-context.asciidoc new file mode 100644 index 00000000000..1831da5a9f8 --- /dev/null +++ b/docs/painless/painless-contexts/painless-watcher-transform-context.asciidoc @@ -0,0 +1,39 @@ +[[painless-watcher-transform-context]] +=== Watcher transform context + +Use a Painless script to {xp_version}/transform-script.html[transform] watch +data into a new payload for use in a response to a condition. + +*Variables* + +`params` (`Map`, read-only):: + User-defined parameters passed in as part of the query. + +`ctx['watch_id']` (`String`, read-only):: + The id of the watch. + +`ctx['execution_time']` (`DateTime`, read-only):: + The start time for the watch. + +`ctx['trigger']['scheduled_time']` (`DateTime`, read-only):: + The scheduled trigger time for the watch. + +`ctx['trigger']['triggered_time']` (`DateTime`, read-only):: + The actual trigger time for the watch. + +`ctx['metadata']` (`Map`, read-only):: + Any metadata associated with the watch. + +`ctx['payload']` (`Map`, read-only):: + The accessible watch data based upon the + {xp_version}/input.html[watch input]. + + +*Return* + +`Object`:: + The new payload. + +*API* + +The standard <> is available. \ No newline at end of file diff --git a/docs/painless/painless-contexts/painless-weight-context.asciidoc b/docs/painless/painless-contexts/painless-weight-context.asciidoc new file mode 100644 index 00000000000..0aef936183c --- /dev/null +++ b/docs/painless/painless-contexts/painless-weight-context.asciidoc @@ -0,0 +1,42 @@ +[[painless-weight-context]] +=== Weight context + +Use a Painless script to create a +{es_version}/index-modules-similarity.html[weight] for use in a +<>. Weight is used to prevent +recalculation of constants that remain the same across documents. + +*Variables* + +`params` (`Map`, read-only):: + User-defined parameters passed in as part of the query. + +`query.boost` (`float`, read-only):: + The boost value if provided by the query. If this is not provided the + value is `1.0f`. + +`field.docCount` (`long`, read-only):: + The number of documents that have a value for the current field. + +`field.sumDocFreq` (`long`, read-only):: + The sum of all terms that exist for the current field. If this is not + available the value is `-1`. + +`field.sumTotalTermFreq` (`long`, read-only):: + The sum of occurrences in the index for all the terms that exist in the + current field. If this is not available the value is `-1`. + +`term.docFreq` (`long`, read-only):: + The number of documents that contain the current term in the index. + +`term.totalTermFreq` (`long`, read-only):: + The total occurrences of the current term in the index. + +*Return* + +`double`:: + A scoring factor used across all documents. + +*API* + +The standard <> is available. \ No newline at end of file diff --git a/docs/painless/painless-operators-array.asciidoc b/docs/painless/painless-operators-array.asciidoc index e91c07acef5..acfb87d30af 100644 --- a/docs/painless/painless-operators-array.asciidoc +++ b/docs/painless/painless-operators-array.asciidoc @@ -184,7 +184,7 @@ brace_access: '[' expression ']' store `def` to `x` <5> declare `def y`; implicit cast `int 1` to `def` -> `def`; - store `def ` to `y`; + store `def` to `y`; <6> declare `int i`; load from `d` -> `def` implicit cast `def` to `1-d int array reference` diff --git a/docs/painless/painless-scripts.asciidoc b/docs/painless/painless-scripts.asciidoc index 87e5b601590..81fdbbe7367 100644 --- a/docs/painless/painless-scripts.asciidoc +++ b/docs/painless/painless-scripts.asciidoc @@ -3,4 +3,4 @@ Scripts are composed of one-to-many <> and are run in a sandbox that determines what local variables are immediately available -along with what APIs are whitelisted for use. \ No newline at end of file +along with what APIs are whitelisted for use.