diff --git a/docs/painless/painless-contexts/painless-score-context.asciidoc b/docs/painless/painless-contexts/painless-score-context.asciidoc index bd1e1de7f77..2bec9021c17 100644 --- a/docs/painless/painless-contexts/painless-score-context.asciidoc +++ b/docs/painless/painless-contexts/painless-score-context.asciidoc @@ -11,8 +11,10 @@ score to documents returned from a query. 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. + Contains the fields of the current document. For single-valued fields, + the value can be accessed via `doc['fieldname'].value`. For multi-valued + fields, this returns the first value; other values can be accessed + via `doc['fieldname'].get(index)` `_score` (`double` read-only):: The similarity score of the current document. @@ -24,4 +26,33 @@ score to documents returned from a query. *API* -The standard <> is available. \ No newline at end of file +The standard <> is available. + +*Example* + +To run this example, first follow the steps in +<>. + +The following query finds all unsold seats, with lower 'row' values +scored higher. + +[source,js] +-------------------------------------------------- +GET /seats/_search +{ + "query": { + "function_score": { + "query": { + "match": { "sold": "false" } + }, + "script_score" : { + "script" : { + "source": "1.0 / doc['row'].value" + } + } + } + } +} +-------------------------------------------------- +// CONSOLE +// TEST[setup:seats] \ 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 index 53b37be52b6..9a8e59350d1 100644 --- a/docs/painless/painless-contexts/painless-similarity-context.asciidoc +++ b/docs/painless/painless-contexts/painless-similarity-context.asciidoc @@ -15,6 +15,9 @@ documents in a query. `params` (`Map`, read-only):: User-defined parameters passed in at query-time. +`weight` (`float`, read-only):: + The weight as calculated by a {ref}/painless-weight-context[weight script] + `query.boost` (`float`, read-only):: The boost value if provided by the query. If this is not provided the value is `1.0f`. @@ -37,12 +40,23 @@ documents in a query. 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. + The number of tokens the current document has in the current field. This + is decoded from the stored {ref}/norms[norms] and may be approximate for + long fields `doc.freq` (`long`, read-only):: The number of occurrences of the current term in the current document for the current field. +Note that the `query`, `field`, and `term` variables are also available to the +{ref}/painless-weight-context[weight context]. They are more efficiently used +there, as they are constant for all documents. + +For queries that contain multiple terms, the script is called once for each +term with that term's calculated weight, and the results are summed. Note that some +terms might have a `doc.freq` value of `0` on a document, for example if a query +uses synonyms. + *Return* `double`:: diff --git a/docs/painless/painless-contexts/painless-sort-context.asciidoc b/docs/painless/painless-contexts/painless-sort-context.asciidoc index 9efd5076688..64c17ad07a6 100644 --- a/docs/painless/painless-contexts/painless-sort-context.asciidoc +++ b/docs/painless/painless-contexts/painless-sort-context.asciidoc @@ -10,8 +10,10 @@ Use a Painless script to 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. + Contains the fields of the current document. For single-valued fields, + the value can be accessed via `doc['fieldname'].value`. For multi-valued + fields, this returns the first value; other values can be accessed + via `doc['fieldname'].get(index)` `_score` (`double` read-only):: The similarity score of the current document. @@ -23,4 +25,37 @@ Use a Painless script to *API* -The standard <> is available. \ No newline at end of file +The standard <> is available. + +*Example* + +To run this example, first follow the steps in +<>. + +To sort results by the length of the `theatre` field, submit the following query: + +[source,js] +---- +GET /_search +{ + "query" : { + "term" : { "sold" : "true" } + }, + "sort" : { + "_script" : { + "type" : "number", + "script" : { + "lang": "painless", + "source": "doc['theatre'].value.length() * params.factor", + "params" : { + "factor" : 1.1 + } + }, + "order" : "asc" + } + } +} + +---- +// CONSOLE +// TEST[setup:seats] \ 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 index ad215d5386b..319b7999aa8 100644 --- a/docs/painless/painless-contexts/painless-weight-context.asciidoc +++ b/docs/painless/painless-contexts/painless-weight-context.asciidoc @@ -3,8 +3,11 @@ Use a Painless script to create a {ref}/index-modules-similarity.html[weight] for use in a -<>. Weight is used to prevent -recalculation of constants that remain the same across documents. +<>. The weight makes up the +part of the similarity calculation that is independent of the document being +scored, and so can be built up front and cached. + +Queries that contain multiple terms calculate a separate weight for each term. *Variables*