---
title: Query unmapped fields without reindexing
description: How ES|QL queries fields that aren't in the index mapping, using the SET unmapped_fields directive.
url: https://www.elastic.co/elastic/docs-builder/docs/3621/reference/query-languages/esql/esql-unmapped-fields
products:
- Elasticsearch
applies_to:
- Elastic Cloud Serverless: Preview
- Elastic Stack: Preview since 9.3
---
# Query unmapped fields without reindexing
ES|QL can query fields that are not defined in your index mapping, with no reindex and no change to the mapping. The [`SET unmapped_fields`](/elastic/docs-builder/docs/3621/reference/query-languages/esql/directives/set#esql-unmapped_fields) directive controls how each query handles them.
An unmapped field is a field in indexed documents that the index' mapping does not define. By default, ES|QL treats such fields as `null` and returns an error if a referenced field is not mapped in any index.
Without this capability, the usual fix is to add the field to your mapping and reindex your data before you can query it. On a large dataset, that reindex can take hours.
## Use cases
Querying unmapped fields helps in several common situations where the mapping does not yet match the data you want to explore:
- **Explore new fields before mapping them**: query the values of a field as soon as it appears, whether it arrives unexpectedly from an integration or an upstream change, then decide later whether the performance gains of formal mapping justify a reindex.
- **Read the real values of a partially mapped field**: when a field is mapped in some indices but not others, get its values everywhere in a single query, including the indices where it is unmapped.
- **Run reusable queries across datasets**: let a query continue when a field is not mapped in the data it runs against. This is useful for shared or saved queries and for data streams whose mappings change between rollovers. You can either ignore the missing data by returning `null` or try to load its values from `_source`.
To extract a value from a JSON string or directly from `_source`, use [`JSON_EXTRACT`](https://www.elastic.co/elastic/docs-builder/docs/3621/reference/query-languages/esql/functions-operators/string-functions/json_extract) Elastic Stack: Preview in 9.4.To extract a subfield from a [`flattened`](https://www.elastic.co/elastic/docs-builder/docs/3621/reference/elasticsearch/mapping-reference/flattened) field, use [`FIELD_EXTRACT`](https://www.elastic.co/elastic/docs-builder/docs/3621/reference/query-languages/esql/functions-operators/string-functions/field_extract) Elastic Stack: Planned Elastic Cloud Serverless: Preview.
## How ES|QL handles unmapped fields
The `unmapped_fields` setting accepts three values, which range from strict to permissive. These values also control how ES|QL resolves a partially unmapped field, one that exists in the mapping of some indices but not others, across a multi-index query.
| Value | What it does | When to use it |
|------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| `DEFAULT` | The query fails when it references a field that is not mapped in any queried index. For a partially mapped field, documents from indices where the field is not mapped return `null`. This is the default behavior. | You want strict schema enforcement and prefer an error when a field is completely unmapped. |
| `NULLIFY` | Fields that are not mapped in any queried index return `null`. Partially mapped fields behave as they do in `DEFAULT`: documents from indices where the field is not mapped return `null`. | You want a reusable query to continue when a field is not available in a dataset. |
| `LOAD` Elastic Stack: Preview since 9.4 | ES|QL loads a fully unmapped field from the stored [`_source`](https://www.elastic.co/elastic/docs-builder/docs/3621/reference/elasticsearch/mapping-reference/mapping-source-field) as `keyword`. For a partially mapped field, it loads values from `_source` where the field is unmapped. Fields absent from `_source` return `null`.Elastic Stack: Planned For a partially mapped field with a non-`keyword` type, `LOAD` converts the loaded values to the field's mapped type where possible. | You need the real values of a fully or partially unmapped field, so that you can filter or aggregate on it. |
For the full syntax, refer to the [`SET unmapped_fields`](/elastic/docs-builder/docs/3621/reference/query-languages/esql/directives/set#esql-unmapped_fields) reference.
Reading the real values of an unmapped field with `LOAD` is newer than the other behaviors. Earlier versions can nullify unmapped fields (`NULLIFY`) but can't load their real values.
## Limitations
`LOAD` does not support every command, function, and field type. For the current restrictions, refer to the [`SET unmapped_fields`](/elastic/docs-builder/docs/3621/reference/query-languages/esql/directives/set#esql-unmapped_fields) reference.
One restriction worth planning around is performance: reading from the stored [`_source`](https://www.elastic.co/elastic/docs-builder/docs/3621/reference/elasticsearch/mapping-reference/mapping-source-field) is slower than querying a mapped field, because the values aren't stored in a data structure optimized for fast access. The trade-off is that the data is available immediately without a full reindex.
## Unmapped fields and runtime fields
Unmapped fields differ from runtime fields. A runtime field is a computed field that can be defined in the index mapping, while an unmapped field is not in the mapping at all but can be present in documents. If a runtime field is part of the index mapping, ES|QL treats it like any other mapped field. In ES|QL, you create computed columns with the [`EVAL`](https://www.elastic.co/elastic/docs-builder/docs/3621/reference/query-languages/esql/commands/eval) command. To learn more, refer to [runtime fields](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3621/manage-data/data-store/mapping/runtime-fields).
## Related resources
To go deeper on unmapped fields and related capabilities, refer to these pages:
- [`SET unmapped_fields`](/elastic/docs-builder/docs/3621/reference/query-languages/esql/directives/set#esql-unmapped_fields): the directive syntax, accepted values, and `LOAD` limitations.
- [`JSON_EXTRACT`](https://www.elastic.co/elastic/docs-builder/docs/3621/reference/query-languages/esql/functions-operators/string-functions/json_extract): extract values from JSON strings and `_source`.
- [Retrieve unmapped fields](/elastic/docs-builder/docs/3621/reference/elasticsearch/rest-apis/retrieve-selected-fields#retrieve-unmapped-fields): the equivalent `include_unmapped` option in the search `fields` API.
- [ES|QL unmapped fields on Elastic Search Labs](https://www.elastic.co/search-labs/blog/esql-unmapped-fields): the blog post that introduces the feature.