[[painless-runtime-fields-context]]
=== Runtime fields context
Use a Painless script to calculate and emit
<<painless-runtime-fields,runtime field>> values.

See the {ref}/runtime.html[runtime fields] documentation for more information
about how to use runtime fields.

*Methods*

--
[[runtime-emit-method]]
// tag::runtime-field-emit[]
`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 
<<painless-execute-runtime-context,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`
[%collapsible%open]
====
The signature for `emit` depends on the `type` of the field.

[horizontal]
`boolean`::   `emit(boolean)`
`date`::      `emit(long)`
`double`::    `emit(double)`
`geo_point`:: `emit(double lat, double long)`
`ip`::        `emit(String)`
`long`::      `emit(long)`
`keyword`::   `emit(String)`
====
// end::runtime-field-emit[]
--

--
`grok`::
        Defines a {ref}/grok-processor.html[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 {ref}/runtime-examples.html#runtime-examples-grok[Define a runtime field with a grok pattern].
+
.Properties of `grok`
[%collapsible%open]
====
`extract`::
        Indicates the values to return. This method applies only to `grok` and
        `dissect` methods.
====
--

--
`dissect`::
        Defines a {ref}/dissect-processor.html[dissect pattern]. Dissect operates much like grok, but does not accept regular expressions. See {ref}/runtime-examples.html#runtime-examples-dissect[Define a runtime field with a dissect pattern].
+
.Properties of `dissect`
[%collapsible%open]
====
`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.

{ref}/mapping-source-field.html[`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-reference-shared, Painless API>> and
<<painless-api-reference-field, Specialized Field API>> are available.


*Example*

To run the examples, first follow the steps in
<<painless-context-examples, 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
<<painless-field-context,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:

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

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,
{es} evaluates the included Painless script and dynamically generates a value
based on the script definition:

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

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

[source,console-result]
----
{
  ...
  "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
        }
      ]
    }
  }
}
----
// TESTRESPONSE[s/\.\.\./"took" : $body.took,"timed_out" : $body.timed_out,"_shards" : $body._shards,/]
