Skip to content

Instantly share code, notes, and snippets.

Last active May 30, 2016 16:50
Show Gist options
  • Save terrancesnyder/95f79ad585f9ee55caac16d5db7f8a56 to your computer and use it in GitHub Desktop.
Save terrancesnyder/95f79ad585f9ee55caac16d5db7f8a56 to your computer and use it in GitHub Desktop.
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