Map a runtime field

edit

This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.

You map runtime fields by adding a runtime section under the mapping definition and defining a Painless script. This script has access to the entire context of a document, including the original _source and any mapped fields plus their values. At query time, the script runs and generates values for each scripted field that is required for the query.

When defining a Painless script to use with runtime fields, you must include emit to emit calculated values. For example, 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.

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"}
    }
  }
}

The runtime section can be any of these data types:

  • boolean
  • date
  • double
  • geo_point
  • ip
  • keyword
  • long

Runtime fields with a type of date can accept the format parameter exactly as the date field type.

If dynamic field mapping is enabled where the dynamic parameter is set to runtime, new fields are automatically added to the index mapping as runtime fields:

PUT my-index
{
  "mappings": {
    "dynamic": "runtime",
    "properties": {
      "@timestamp": {
        "type": "date"
      }
    }
  }
}

Define runtime fields without a script

edit

You can define a runtime field in the mapping definition without a script. At query time, Elasticsearch looks in _source for a field with the same name and returns a value if one exists. If a field with the same name doesn’t exist, the response doesn’t include any values for that runtime field.

PUT my-index/
{
  "mappings": {
    "runtime": {
      "day_of_week": {
        "type": "keyword"
      }
    }
  }
}