Runtime fields context

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.

Use a Painless script to calculate and emit runtime field values.

See the runtime fields documentation for more information about how to use runtime fields.

Variables

params (Map, read-only)
User-defined parameters passed in as part of the query.
doc (Map, read-only)
Contains the fields of the specified document where each field is a List of values.
params['_source'] (Map, read-only)
Contains extracted JSON in a Map and List structure for the fields existing in a stored document.

Return

void
No expected return value.

API

Both the standard Painless API and Specialized Field API are available.

Example

To run the examples, first follow the steps in context examples.

Then, run the following request to define a runtime field named day_of_week. This field contains a script with the same source defined in Field context, but also uses an emit function that runtime fields require when defining a Painless script.

Because day_of_week is a runtime field, it isn’t indexed, and the included script only runs at query time:

PUT seats/_mapping
{
  "runtime": {
    "day_of_week": {
      "type": "keyword",
      "script": {
        "source": "emit(doc['datetime'].value.getDayOfWeekEnum().toString())"
      }
    }
  }
}

After defining the runtime field and script in the mappings, you can run a query that includes a terms aggregation for day_of_week. When the query runs, Elasticsearch evaluates the included Painless script and dynamically generates a value based on the script definition:

GET seats/_search
{
  "size": 0,
  "fields": [
    "time",
    "day_of_week"
    ],
    "aggs": {
      "day_of_week": {
        "terms": {
          "field": "day_of_week",
          "size": 10
        }
      }
    }
}

The response includes day_of_week for each hit. Elasticsearch calculates the value for this field dynamically at search time by operating on the datetime field defined in the mappings.

{
  ...
  "hits" : {
    "total" : {
      "value" : 11,
      "relation" : "eq"
    },
    "max_score" : null,
    "hits" : [ ]
  },
  "aggregations" : {
    "day_of_week" : {
      "doc_count_error_upper_bound" : 0,
      "sum_other_doc_count" : 0,
      "buckets" : [
        {
          "key" : "TUESDAY",
          "doc_count" : 5
        },
        {
          "key" : "THURSDAY",
          "doc_count" : 4
        },
        {
          "key" : "MONDAY",
          "doc_count" : 1
        },
        {
          "key" : "SUNDAY",
          "doc_count" : 1
        }
      ]
    }
  }
}