127 lines
5.3 KiB
Plaintext
127 lines
5.3 KiB
Plaintext
|
[[script-fields-api]]
|
|||
|
|
== Access fields in a document with the `field` API
|
|||
|
|
++++
|
|||
|
|
<titleabbrev>Access fields in a document</titleabbrev>
|
|||
|
|
++++
|
|||
|
|
|
|||
|
|
beta::["The `field` API is still in development and should be considered a beta feature. The API is subject to change and this iteration is likely not the final state. For feature status, refer to {es-issue}78920[#78920]."]
|
|||
|
|
|
|||
|
|
Use the `field` API to access document fields:
|
|||
|
|
|
|||
|
|
[source,painless]
|
|||
|
|
----
|
|||
|
|
field('my_field').get(<default_value>)
|
|||
|
|
----
|
|||
|
|
|
|||
|
|
This API fundamentally changes how you access documents in Painless. Previously,
|
|||
|
|
you had to access the `doc` map with the field name that you wanted to access:
|
|||
|
|
|
|||
|
|
[source,painless]
|
|||
|
|
----
|
|||
|
|
doc['my_field'].value
|
|||
|
|
----
|
|||
|
|
|
|||
|
|
Accessing document fields this way didn't handle missing values or missing
|
|||
|
|
mappings, which meant that to write robust Painless scripts, you needed to
|
|||
|
|
include logic to check that both fields and values exist.
|
|||
|
|
|
|||
|
|
Instead, use the `field` API, which is the preferred approach to access
|
|||
|
|
documents in Painless. The `field` API handles missing values, and will evolve
|
|||
|
|
to abstract access to `_source` and `doc_values`.
|
|||
|
|
|
|||
|
|
NOTE: Some fields aren't yet compatible with the `fields` API, such as `text` or
|
|||
|
|
`geo` fields. Continue using `doc` to access field types that the `field` API
|
|||
|
|
doesn't support.
|
|||
|
|
|
|||
|
|
The `field` API returns a `Field` object that iterates over fields with
|
|||
|
|
multiple values, providing access to the underlying value through the
|
|||
|
|
`get(<default_value>)` method, as well as type conversion and helper methods.
|
|||
|
|
|
|||
|
|
The `field` API returns the default value that you specify, regardless of
|
|||
|
|
whether the field exists or has any values for the current document.
|
|||
|
|
This means that the `field` API can handle missing values without requiring
|
|||
|
|
additional logic. For a reference type such as `keyword`, the default
|
|||
|
|
value can be `null`. For a primitive type such as `boolean` or `long`, the
|
|||
|
|
default value must be a matching primitive type, such as `false` or `1`.
|
|||
|
|
|
|||
|
|
[discrete]
|
|||
|
|
=== Convenient, simpler access
|
|||
|
|
Instead of explicitly calling the `field` API with the `get()` method, you can
|
|||
|
|
include the `$` shortcut. Just include the `$` symbol, field name, and a default
|
|||
|
|
value, in case the field doesn't have a value:
|
|||
|
|
|
|||
|
|
[source,painless]
|
|||
|
|
----
|
|||
|
|
$(‘field’, <default_value>)
|
|||
|
|
----
|
|||
|
|
|
|||
|
|
With these enhanced capabilities and simplified syntax, you can write scripts
|
|||
|
|
that are shorter, less complex, and easier to read. For example, the following
|
|||
|
|
script uses the outdated syntax to determine the difference in milliseconds
|
|||
|
|
between two complex `datetime` values from an indexed document:
|
|||
|
|
|
|||
|
|
[source,painless]
|
|||
|
|
----
|
|||
|
|
if (doc.containsKey('start') && doc.containsKey('end')) {
|
|||
|
|
if (doc['start'].size() > 0 && doc['end'].size() > 0) {
|
|||
|
|
ZonedDateTime start = doc['start'].value;
|
|||
|
|
ZonedDateTime end = doc['end'].value;
|
|||
|
|
return ChronoUnit.MILLIS.between(start, end);
|
|||
|
|
} else {
|
|||
|
|
return -1;
|
|||
|
|
}
|
|||
|
|
} else {
|
|||
|
|
return -1;
|
|||
|
|
}
|
|||
|
|
----
|
|||
|
|
|
|||
|
|
Using the `field` API, you can write this same script much more succinctly,
|
|||
|
|
without requiring additional logic to determine whether fields exist before
|
|||
|
|
operating on them:
|
|||
|
|
|
|||
|
|
[source,painless]
|
|||
|
|
----
|
|||
|
|
ZonedDateTime start = field('start').get(null);
|
|||
|
|
ZonedDateTime end = field('end').get(null);
|
|||
|
|
return start == null || end == null ? -1 : ChronoUnit.MILLIS.between(start, end)
|
|||
|
|
----
|
|||
|
|
|
|||
|
|
[discrete]
|
|||
|
|
=== Supported mapped field types
|
|||
|
|
The following table indicates the mapped field types that the `field` API
|
|||
|
|
supports. For each supported type, values are listed that are returned by the
|
|||
|
|
`field` API (from the `get` and `as<Type>` methods) and the `doc` map (from the
|
|||
|
|
`getValue` and `get` methods).
|
|||
|
|
|
|||
|
|
NOTE: The `fields` API currently doesn't support some fields, but you can still
|
|||
|
|
access those fields through the `doc` map. For the most current list of
|
|||
|
|
supported fields, refer to {es-issue}79105[#79105].
|
|||
|
|
|
|||
|
|
[cols="1,1,1,1,1",options="header",]
|
|||
|
|
|========
|
|||
|
|
|Mapped field type
|
|||
|
|
2+|Returned type from `field`
|
|||
|
|
2+|Returned type from `doc`
|
|||
|
|
h| h|`get` h|`as<Type>` h|`getValue` h|`get`
|
|||
|
|
|`binary` |`ByteBuffer` |- |`BytesRef` |`BytesRef`
|
|||
|
|
|`boolean` |`boolean` |- |`boolean` |`Boolean`
|
|||
|
|
|`keyword` |`String` |- |`String` |`String`
|
|||
|
|
|`long` |`long` |- |`long` |`Long`
|
|||
|
|
|`integer` |`int` |- |`long` |`Long`
|
|||
|
|
|`short` |`short` |- |`long` |`Long`
|
|||
|
|
|`byte` |`byte` |- |`long` |`Long`
|
|||
|
|
|`double` |`double` |- |`double` |`Double`
|
|||
|
|
|`scaled_float` |`double` |- |`double` |`Double`
|
|||
|
|
|`half_float` |`float` |- |`double` |`Double`
|
|||
|
|
|`unsigned_long` |`long` |`BigInteger` |`long` |`Long`
|
|||
|
|
|`date` |`ZonedDateTime` |- |`ZonedDateTime` |`ZonedDateTime`
|
|||
|
|
|`date_nanos` |`ZonedDateTime` |- |`ZonedDateTime` |`ZonedDateTime`
|
|||
|
|
|`ip` |`IpAddress` |`String` |`String` |`String`
|
|||
|
|
|`_version` |`long` |- |`long` |`Long`
|
|||
|
|
|`_seq_no` |`long` |- |`long` |`Long`
|
|||
|
|
|`version` |`Version` |`String` |`String` |`String`
|
|||
|
|
|`murmur3` |`long` |- |`long` |`Long`
|
|||
|
|
|`constant_keyword` |`String` |- |`String` |`String`
|
|||
|
|
|`wildcard` |`String` |- |`String` |`String`
|
|||
|
|
|`flattened` |`String` |- |`String` |`String`
|
|||
|
|
|========
|