Skip to content

Instantly share code, notes, and snippets.

Last active May 30, 2016
What would you like to do?
Date Math

Date Support

The dates used within the platform support more than simple date/time constraints. Almost all dates within the platform are strings and have special semantics when dealing with periodicity as well as general date/math functions that make it much easier to specify effective start/stop period and work within date ranges.

Basic Date Format

The basic date format is defined as YYYY-MM-DDThh:mm:ssZ where:

  • YYYY is the year.
  • MM is the month.
  • DD is the day of the month.
  • hh is the hour of the day as on a 24-hour clock.
  • mm is minutes.
  • ss is seconds.
  • Z is a literal 'Z' character indicating that this string representation of the date is in UTC

Note that no time zone can be specified; the String representations of dates is always expressed in Coordinated Universal Time (UTC).

Here is an example value:

  • 1972-05-20T17:33:18Z

Date Math Syntax

Date math expressions consist either adding some quantity of time in a specified unit, or rounding the current time by a specified unit. expressions can be chained and are evaluated left to right.

For example: this represents a point in time two months from now:


This is one day ago:

  • NOW-1DAY

A slash is used to indicate rounding. This represents the beginning of the current hour:


The following example computes (with millisecond precision) the point in time six months and three days into the future and then rounds that time to the beginning of that day:


Note that while date math is most commonly used relative to NOW it can be applied to any fixed moment in time as well:

  • 1972-05-20T17:33:18.772Z+6MONTHS+3DAYS/DAY

You can optionally include fractional seconds if you wish, although any precision beyond milliseconds will be ignored. Here are example values with sub-seconds:

  • 1972-05-20T17:33:18.772Z
  • 1972-05-20T17:33:18.77Z
  • 1972-05-20T17:33:18.7Z
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment