Map a runtime field

edit

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.

For example, the script in the following request calculates 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"
      }
    }
  }
}

Updating and removing runtime fields

edit

You can update or remove runtime fields at any time. To replace an existing runtime field, add a new runtime field to the mappings with the same name. To remove a runtime field from the mappings, set the value of the runtime field to null:

PUT my-index/_mapping
{
 "runtime": {
   "day_of_week": null
 }
}