elasticsearch/docs/reference/search/request/script-fields.asciidoc

[[request-body-search-script-fields]]
==== Script Fields

Allows to return a <<modules-scripting,script
evaluation>> (based on different fields) for each hit, for example:

[source,console]
--------------------------------------------------
GET /_search
{
    "query" : {
        "match_all": {}
    },
    "script_fields" : {
        "test1" : {
            "script" : {
                "lang": "painless",
                "source": "doc['price'].value * 2"
            }
        },
        "test2" : {
            "script" : {
                "lang": "painless",
                "source": "doc['price'].value * params.factor",
                "params" : {
                    "factor"  : 2.0
                }
            }
        }
    }
}
--------------------------------------------------
// TEST[setup:sales]

Script fields can work on fields that are not stored (`price` in
the above case), and allow to return custom values to be returned (the
evaluated value of the script).

Script fields can also access the actual `_source` document and
extract specific elements to be returned from it by using `params['_source']`.
Here is an example:

[source,console]
--------------------------------------------------
GET /_search
    {
        "query" : {
            "match_all": {}
        },
        "script_fields" : {
            "test1" : {
                "script" : "params['_source']['message']"
            }
        }
    }
--------------------------------------------------
// TEST[setup:twitter]

Note the `_source` keyword here to navigate the json-like model.

It's important to understand the difference between
`doc['my_field'].value` and `params['_source']['my_field']`. The first,
using the doc keyword, will cause the terms for that field to be loaded to
memory (cached), which will result in faster execution, but more memory
consumption. Also, the `doc[...]` notation only allows for simple valued
fields (you can't return a json object from it) and makes sense only for
non-analyzed or single term based fields. However, using `doc` is
still the recommended way to access values from the document, if at all
possible, because `_source` must be loaded and parsed every time it's used.
Using `_source` is very slow.