ES|QL `FIELD_EXTRACT` function

Extracts a sub-field value from a flattened field as a keyword.

Parameters

field: The root of a flattened mapping field. If null, the function returns null.
path: Literal name of the flattened sub-field to extract (e.g. "host.name"). Brackets and array indices are not supported. If null, the function returns null.

Description

Extracts the value of a single sub-field from a flattened field root as keyword.

The first argument must be a field whose ES mapping type is flattened (the root of the flattened object). The second argument is the literal name of the sub-field to extract, that is, exactly the dotted key as stored in doc values for the flattened root. For example, field_extract(resource.attributes, "host.name") looks up the literal storage key host.name. The dot is part of the key, not a path separator. Nested objects in the original document also collapse to dotted keys (an input {"a":{"b":"x"}} is stored as the flat key a.b), so the same dotted form addresses both flat and originally-nested sub-fields.

JSONPath syntax is not supported: brackets (['host.name']) and array indices (tags[0]) are rejected. Path matching is case-sensitive.

Returns null if either argument is null, if no sub-field with that name exists, or if the stored value is JSON null. Returns null and emits a warning if the root value is not valid JSON.

String values are returned without surrounding quotes, and numbers and booleans as their string representation. When the sub-field is multi-valued in the flattened field, the result is a multi-valued keyword block. Because the underlying mapper flattens nested objects into dotted keys at index time, a sub-field whose value is itself a JSON object has no leaf at the requested key in the flat storage and the function returns null. The dotted child paths (a.b, a.b.c, ...) still address the leaves directly. Inside a multi-value sub-field, JSON object elements are likewise absent from the flat storage and are skipped; nested JSON arrays are flattened recursively so all scalar leaves end up in the resulting multi-value block.

Supported types

field	path	result
flattened The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Preview since 9.5 This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.	keyword	keyword
flattened The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats. Availability Preview since 9.5 This functionality is in technical preview and is ready for evaluation. Use with caution in production; it is not recommended for mission-critical workloads. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. Specific Support terms apply. Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments. This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.	text	keyword

Example

FROM flattened_otel_logs
| WHERE @timestamp == "2020-01-01T00:02:48.461Z"
| EVAL hn = field_extract(resource.attributes, "host.name")
| KEEP hn

hn:keyword
infra-filebeat-6vjxr

Note

FIELD_EXTRACT reads from the flattened field's doc values, so a multi-valued sub-field comes back as a sorted, de-duplicated keyword set: the original document order is not preserved and repeated values are collapsed. This is intrinsic to how the flattened mapping type stores leaf arrays, not to the function; use MV_SORT if you need a defined order downstream. For the other flattened caveats - values are always keyword, dotted-key resolution, and objects or missing keys returning null - see ES|QL and flattened fields.

MATCH, MATCH_PHRASE, and the : operator accept a FIELD_EXTRACT expression and match it at runtime. KQL, QSTR, and KNN require a directly mapped field, so they do not accept a FIELD_EXTRACT expression as an argument; use ==, LIKE, RLIKE, or WILDCARD to filter on an extracted value with those.