Elastic
Loading

Runtime fields context

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.

Methods

emit

(Required) Accepts the values from the script valuation. Scripts can call the emit method multiple times to emit multiple values.

The emit method applies only to scripts used in a runtime fields context.

Important

The emit method cannot accept null values. Do not call this method if the referenced fields do not have any values.

Signatures of `emit`

The signature for emit depends on the type of the field.

boolean
emit(boolean)
date
emit(long)
double
emit(double)
geo_point
emit(double lat, double lon)
ip
emit(String)
long
emit(long)
keyword

emit(String)

grok

Defines a grok pattern to extract structured fields out of a single text field within a document. A grok pattern is like a regular expression that supports aliased expressions that can be reused. See Define a runtime field with a grok pattern.

Properties of `grok`
extract
Indicates the values to return. This method applies only to grok and dissect methods.
dissect

Defines a dissect pattern. Dissect operates much like grok, but does not accept regular expressions. See Define a runtime field with a dissect pattern.

Properties of `dissect`
extract
Indicates the values to return. This method applies only to grok and dissect methods.

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