Datetime Input

There are several common ways datetimes are used as input for a script determined by the Painless context. Typically, datetime input will be accessed from parameters specified by the user, from an original source document, or from an indexed document.

Use the params section during script specification to pass in a numeric datetime or string datetime as a script input. Access to user-defined parameters within a script is dependent on the Painless context, though, the parameters are most commonly accessible through an input called params.

Examples

• Parse a numeric datetime from user parameters to a complex datetime

  • Input:

    ...
    "script": {
        ...
        "params": {
            "input_datetime": 434931327000
        }
    }
    ...
    

  • Script:

    long inputDateTime = params['input_datetime'];
    Instant instant = Instant.ofEpochMilli(inputDateTime);
    ZonedDateTime zdt = ZonedDateTime.ofInstant(instant, ZoneId.of('Z'));
    

• Parse a string datetime from user parameters to a complex datetime

  • Input:

    ...
    "script": {
        ...
        "params": {
            "input_datetime": "custom y 1983 m 10 d 13 22:15:30 Z"
        }
    }
    ...
    

  • Script:

    String datetime = params['input_datetime'];
    DateTimeFormatter dtf = DateTimeFormatter.ofPattern(
            "'custom' 'y' yyyy 'm' MM 'd' dd HH:mm:ss VV");
    ZonedDateTime zdt = ZonedDateTime.parse(datetime, dtf);
    

    1. This uses a custom DateTimeFormatter.

Use an original source document as a script input to access a numeric datetime or string datetime for a specific field within that document. Access to an original source document within a script is dependent on the Painless context and is not always available. An original source document is most commonly accessible through an input called ctx['_source'] or params['_source'].

Examples

• Parse a numeric datetime from a sourced document to a complex datetime

  • Input:

    {
      ...
      "input_datetime": 434931327000
      ...
    }
    

  • Script:

    long inputDateTime = ctx['_source']['input_datetime'];
    Instant instant = Instant.ofEpochMilli(inputDateTime);
    ZonedDateTime zdt = ZonedDateTime.ofInstant(instant, ZoneId.of('Z'));
    

    1. Access to _source is dependent on the Painless context.

• Parse a string datetime from a sourced document to a complex datetime

  • Input:

    {
      ...
      "input_datetime": "1983-10-13T22:15:30Z"
      ...
    }
    

  • Script:

    String datetime = params['_source']['input_datetime'];
    ZonedDateTime zdt = ZonedDateTime.parse(datetime);
    

    1. Access to _source is dependent on the Painless context.
    2. The parse method uses ISO 8601 by default.

Use an indexed document as a script input to access a complex datetime for a specific field within that document where the field is mapped as a standard date or a nanosecond date. Numeric datetime fields mapped as numeric and string datetime fields mapped as keyword are accessible through an indexed document as well. Access to an indexed document within a script is dependent on the Painless context and is not always available. An indexed document is most commonly accessible through an input called doc.

Examples

• Format a complex datetime from an indexed document to a string datetime

  • Assumptions:

    • The field input_datetime exists in all indexes as part of the query
    • All indexed documents contain the field input_datetime

  • Mappings:

    {
      "mappings": {
        ...
        "properties": {
          ...
          "input_datetime": {
            "type": "date"
          }
          ...
        }
        ...
      }
    }
    

  • Script:

    ZonedDateTime input = doc['input_datetime'].value;
    String output = input.format(DateTimeFormatter.ISO_INSTANT);
    

    1. This uses a built-in DateTimeFormatter.

• Find the difference between two complex datetimes from an indexed document

  • Assumptions:

    • The fields start and end may not exist in all indexes as part of the query
    • The fields start and end may not have values in all indexed documents

  • Mappings:

    {
      "mappings": {
        ...
        "properties": {
          ...
          "start": {
            "type": "date"
          },
          "end": {
            "type": "date"
          }
          ...
        }
        ...
      }
    }
    

  • Script:

    if (doc.containsKey('start') && doc.containsKey('end')) {
    
        if (doc['start'].size() > 0 && doc['end'].size() > 0) {
    
            ZonedDateTime start = doc['start'].value;
            ZonedDateTime end = doc['end'].value;
            long differenceInMillis = ChronoUnit.MILLIS.between(start, end);
    
            // handle difference in times
        } else {
            // handle fields without values
        }
    } else {
        // handle index with missing fields
    }
    

    1. When a query’s results span multiple indexes, some indexes may not contain a specific field. Use the containsKey method call on the doc input to ensure a field exists as part of the index for the current document.
    2. Some fields within a document may have no values. Use the size method call on a field within the doc input to ensure that field has at least one value for the current document.