mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-29 01:44:36 -04:00
80 lines
3.1 KiB
Markdown
80 lines
3.1 KiB
Markdown
---
|
|
mapped_pages:
|
|
- https://www.elastic.co/guide/en/elasticsearch/painless/current/painless-runtime-fields.html
|
|
products:
|
|
- id: painless
|
|
---
|
|
|
|
# Use painless scripts in runtime fields [painless-runtime-fields]
|
|
|
|
A runtime field is a field that is evaluated at query time. When you define a runtime field, you can immediately use it in search requests, aggregations, filtering, and sorting.
|
|
|
|
When defining a runtime field, you can include a Painless script that is evaluated at query time. This script has access to the entire context of a document, including the original document [`_source` field](docs-content://explore-analyze/scripting/modules-scripting-fields.md) and any mapped fields plus their values. At query time, the script runs and generates values for each scripted field that is included in the query.
|
|
|
|
You can map a runtime field in the `runtime` section under the mapping definition, or define runtime fields that exist only as part of a search request. The script syntax is the same, regardless of where you define the runtime field.
|
|
|
|
::::{important}
|
|
When defining a Painless script to use with runtime fields, you must include `emit` to return calculated values.
|
|
::::
|
|
|
|
|
|
|
|
## Define a runtime field in the mapping [painless-runtime-fields-mapping]
|
|
|
|
Add a `runtime` section under the [mapping definition](docs-content://manage-data/data-store/mapping/map-runtime-field.md) to explore your data without indexing fields.
|
|
|
|
The script in the following request extracts the day of the week from the `@timestamp` field, which is defined as a `date` type. The script calculates the day of the week based on the value of `@timestamp`, and uses `emit` to return the calculated value.
|
|
|
|
```console
|
|
PUT my-index/
|
|
{
|
|
"mappings": {
|
|
"runtime": {
|
|
"day_of_week": {
|
|
"type": "keyword",
|
|
"script": {
|
|
"source":
|
|
"""emit(doc['@timestamp'].value.dayOfWeekEnum
|
|
.getDisplayName(TextStyle.FULL, Locale.ROOT))"""
|
|
}
|
|
}
|
|
},
|
|
"properties": {
|
|
"@timestamp": {"type": "date"}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
## Define a runtime field only in a search request [painless-runtime-fields-query]
|
|
|
|
Use runtime fields in a search request to create a field that exists [only as part of the query](docs-content://manage-data/data-store/mapping/define-runtime-fields-in-search-request.md). You can also [override field values](docs-content://manage-data/data-store/mapping/override-field-values-at-query-time.md) at query time for existing fields without modifying the field itself.
|
|
|
|
This flexibility allows you to experiment with your data schema and fix mistakes in your index mapping without reindexing your data.
|
|
|
|
In the following request, the values for the `day_of_week` field are calculated dynamically, and only within the context of this search request:
|
|
|
|
```console
|
|
GET my-index/_search
|
|
{
|
|
"runtime_mappings": {
|
|
"day_of_week": {
|
|
"type": "keyword",
|
|
"script": {
|
|
"source":
|
|
"""emit(doc['@timestamp'].value.dayOfWeekEnum
|
|
.getDisplayName(TextStyle.FULL, Locale.ROOT))"""
|
|
}
|
|
}
|
|
},
|
|
"aggs": {
|
|
"day_of_week": {
|
|
"terms": {
|
|
"field": "day_of_week"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|