---
title: ES|QL FIELD_EXTRACT function
description: 
url: https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql/functions-operators/string-functions/field_extract
products:
  - Elasticsearch
---

# ES|QL FIELD_EXTRACT function
<applies-to>
  - Elastic Cloud Serverless: Preview
  - Elastic Stack: Planned
</applies-to>

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

## Syntax

![Embedded](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql/images/generated/x-pack-esql/functions/field_extract.svg)


## Parameters

<definitions>
  <definition term="field">
    The root of a `flattened` mapping field. If `null`, the function returns `null`.
  </definition>
  <definition term="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`.
  </definition>
</definitions>


## Description

Extracts the value of a single sub-field from a [`flattened` field](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/mapping-reference/flattened) 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 <applies-to>Elastic Stack: Planned</applies-to> | keyword | keyword |
| flattened <applies-to>Elastic Stack: Planned</applies-to> | text    | keyword |


## Example

```esql
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 |