﻿---
title: Runtime fields context
description: 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...
url: https://www.elastic.co/elastic/docs-builder/docs/2437/reference/scripting-languages/painless/painless-runtime-fields-context
products:
  - Painless
---

# Runtime fields context
Use a Painless script to calculate and emit [runtime field](https://www.elastic.co/elastic/docs-builder/docs/2437/reference/scripting-languages/painless/use-painless-scripts-in-runtime-fields) values.
See the [runtime fields](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2437/manage-data/data-store/mapping/runtime-fields) documentation for more information about how to use runtime fields.
**Methods**

<definitions>
  <definition term="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](/elastic/docs-builder/docs/2437/reference/scripting-languages/painless/painless-api-examples#painless-execute-runtime-context).
    <important>
      The `emit` method cannot accept `null` values. Do not call this method if the referenced fields do not have any values.
    </important>
  </definition>
</definitions>

<dropdown title="Signatures of emit">
  The signature for `emit` depends on the `type` of the field.
  <definitions>
    <definition term="boolean">
      `emit(boolean)`
    </definition>
    <definition term="date">
      `emit(long)`
    </definition>
    <definition term="double">
      `emit(double)`
    </definition>
    <definition term="geo_point">
      `emit(double lat, double lon)`
    </definition>
    <definition term="ip">
      `emit(String)`
    </definition>
    <definition term="long">
      `emit(long)`
    </definition>
    <definition term="keyword">
      `emit(String)`
    </definition>
  </definitions>
</dropdown>

<definitions>
  <definition term="grok">
    Defines a [grok pattern](https://www.elastic.co/elastic/docs-builder/docs/2437/reference/enrich-processor/grok-processor) 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](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2437/manage-data/data-store/mapping/explore-data-with-runtime-fields#runtime-examples-grok).
    <dropdown title="Properties of grok">
      <definitions>
        <definition term="extract">
          Indicates the values to return. This method applies only to `grok` and `dissect` methods.
        </definition>
      </definitions>
    </dropdown>
  </definition>
  <definition term="dissect">
    Defines a [dissect pattern](https://www.elastic.co/elastic/docs-builder/docs/2437/reference/enrich-processor/dissect-processor). Dissect operates much like grok, but does not accept regular expressions. See [Define a runtime field with a dissect pattern](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/2437/manage-data/data-store/mapping/explore-data-with-runtime-fields#runtime-examples-dissect).
    <dropdown title="Properties of dissect">
      <definitions>
        <definition term="extract">
          Indicates the values to return. This method applies only to `grok` and `dissect` methods.
        </definition>
      </definitions>
    </dropdown>
  </definition>
</definitions>

**Variables**
<definitions>
  <definition term="params (Map, read-only)">
    User-defined parameters passed in as part of the query.
  </definition>
  <definition term="doc (Map, read-only)">
    Contains the fields of the specified document where each field is a `List` of values.
  </definition>
  <definition term="params['_source'] (Map, read-only)">
    Contains extracted JSON in a `Map` and `List` structure for the fields existing in a stored document.
  </definition>
</definitions>

**Return**
<definitions>
  <definition term="void">
    No expected return value.
  </definition>
</definitions>

**API**
Both the standard [Painless API](https://www.elastic.co/guide/en/elasticsearch/painless/current/painless-api-reference-shared.html) and [Specialized Field API](https://www.elastic.co/guide/en/elasticsearch/painless/current/painless-api-reference-field.html) are available.
**Example**
To run the examples, first follow the steps in [context examples](https://www.elastic.co/elastic/docs-builder/docs/2437/reference/scripting-languages/painless/painless-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](https://www.elastic.co/elastic/docs-builder/docs/2437/reference/scripting-languages/painless/painless-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:
```json

{
  "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:
```json

{
  "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.
```json
{
  ...
  "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
        }
      ]
    }
  }
}
```