Accessing document fields and special variables
editAccessing document fields and special variables
editDepending on where a script is used, it will have access to certain special variables and document fields.
Update scripts
editA script used in the update,
update-by-query, or reindex
API will have access to the ctx
variable which exposes:
|
Access to the document |
|
The operation that should be applied to the document: |
|
Access to document meta-fields, some of which may be read-only. |
Search and Aggregation scripts
editWith the exception of script fields which are executed once per search hit, scripts used in search and aggregations will be executed once for every document which might match a query or an aggregation. Depending on how many documents you have, this could mean millions or billions of executions: these scripts need to be fast!
Field values can be accessed from a script using
doc-values, or
stored fields or _source
field, which are explained below.
Accessing the score of a document within a script
editScripts used in the function_score
query,
in script-based sorting, or in
aggregations have access to the _score
variable which
represents the current relevance score of a document.
Here’s an example of using a script in a
function_score
query to alter the
relevance _score
of each document:
PUT my_index/_doc/1?refresh { "text": "quick brown fox", "popularity": 1 } PUT my_index/_doc/2?refresh { "text": "quick fox", "popularity": 5 } GET my_index/_search { "query": { "function_score": { "query": { "match": { "text": "quick brown fox" } }, "script_score": { "script": { "lang": "expression", "source": "_score * doc['popularity']" } } } } }
Doc Values
editBy far the fastest most efficient way to access a field value from a
script is to use the doc['field_name']
syntax, which retrieves the field
value from doc values. Doc values are a columnar field value
store, enabled by default on all fields except for analyzed text
fields.
PUT my_index/_doc/1?refresh { "cost_price": 100 } GET my_index/_search { "script_fields": { "sales_price": { "script": { "lang": "expression", "source": "doc['cost_price'] * markup", "params": { "markup": 0.2 } } } } }
Doc-values can only return "simple" field values like numbers, dates, geo- points, terms, etc, or arrays of these values if the field is multi-valued. It cannot return JSON objects.
Missing fields
The doc['field']
will throw an error if field
is missing from the mappings.
In painless
, a check can first be done with doc.containsKey('field')
to guard
accessing the doc
map. Unfortunately, there is no way to check for the
existence of the field in mappings in an expression
script.
Doc values and text
fields
The doc['field']
syntax can also be used for analyzed text
fields
if fielddata
is enabled, but BEWARE: enabling fielddata on a
text
field requires loading all of the terms into the JVM heap, which can be
very expensive both in terms of memory and CPU. It seldom makes sense to
access text
fields from scripts.
Stored Fields and _source
editStored fields — fields explicitly marked as
"store": true
— can be accessed using the
_fields['field_name'].value
or _fields['field_name']
syntax.
The document _source
, which is really just a
special stored field, can be accessed using the _source.field_name
syntax.
The _source
is loaded as a map-of-maps, so properties within object fields
can be accessed as, for example, _source.name.first
.
Prefer doc-values to stored fields
Stored fields (which includes the stored _source
field) are much slower than
doc-values. They are optimised for returning several fields per result,
while doc values are optimised for accessing the value of a specific field in
many documents.
It makes sense to use _source
or stored fields when generating a
script field for the top ten hits from a search
result but, for other search and aggregation use cases, always prefer using
doc values.
For instance:
PUT my_index { "mappings": { "_doc": { "properties": { "title": { "type": "text" }, "first_name": { "type": "text", "store": true }, "last_name": { "type": "text", "store": true } } } } } PUT my_index/_doc/1?refresh { "title": "Mr", "first_name": "Barry", "last_name": "White" } GET my_index/_search { "script_fields": { "source": { "script": { "lang": "painless", "source": "params._source.title + ' ' + params._source.first_name + ' ' + params._source.last_name" } }, "stored_fields": { "script": { "lang": "painless", "source": "params._fields['first_name'].value + ' ' + params._fields['last_name'].value" } } } }
The |
|
The |
Stored vs _source
The _source
field is just a special stored field, so the performance is
similar to that of other stored fields. The _source
provides access to the
original document body that was indexed (including the ability to distinguish
null
values from empty fields, single-value arrays from plain scalars, etc).
The only time it really makes sense to use stored fields instead of the
_source
field is when the _source
is very large and it is less costly to
access a few small stored fields instead of the entire _source
.