Total temporal duration is specified by a phrase: FROM time_interval AGO TO
time_interval AGO. This indicates the beginning and ending of a time interval.
This is an inclusive duration.

FROM

Can be the words "from" or "starting from".

time_interval

A time amount followed by a unit (for example, 1 hour). Fractional amounts are
not supported. The unit may be "minute", "day", "hour" with any
pluralization.

TO

Can be the words "until" or "to".

AGO

(optional) The word "ago"

The TO time_interval AGO portion is optional. If this portion is
unspecified then it is expected that the time interval ends now.

Due to the vagaries of the English language, the from and the
to portions, if both are specified, are interchangeable with regard to
which one specifies the start and which specifies the end. In other words "starting from 1
hour ago to 30 minutes ago" and "starting from 30 minutes ago to 1 hour ago" specify the
same temporal duration.

Total Temporal Duration Examples

The domain specific language allows for some flexibility on how to specify a duration.
The following are examples of various ways you can specify the same duration.

A duration starting 1 hour ago and ending now:

from 1 hour ago

from 1 hour

starting from 1 hour ago

starting from 1 hour

A duration starting 1 hour ago and ending 30 minutes ago:

from 1 hour ago until 30 minutes ago

from 30 minutes ago until 1 hour ago

starting from 1 hour ago to 30 minutes ago

starting from 1 hour to 30 minutes

Temporal Window Width

Temporal window width is the specification of a window. A window may either repeat
within a total temporal duration or it may fill the total temporal duration. This is an
inclusive window. A temporal window width is specified by the phrase: time_interval
WINDOW.

time_interval

A time amount followed by a unit (for example, 1 hour). Fractional amounts are
not supported. The unit may be "minute", day", or "hour" with any
pluralization.

WINDOW

(optional) The word "window".

Temporal Window Width Examples

A fixed window starting 2 hours ago and going until now

2 hour

2 hours

2 hours window

A repeating 30 minute window starting 2 hours ago and repeating every hour until
now. This would result in 2 30-minute wide windows: 2 hours ago and 1 hour ago

30 minute window every 1 hour starting from 2 hours ago

temporal window width skip distance total temporal duration

30 minute windows every 1 hour from 2 hours ago

temporal window width skip distance total temporal duration

Skip Distance

Skip distance is the amount of time between when one temporal window begins and the
next window starts. It is, in effect, the window period. It is specified by the phrase
EVERY time_interval.

time_interval

A time amount followed by a unit (for example, 1 hour). Fractional amounts are
not supported. The unit may be "minute", "day", or "hour" with any
pluralization.

EVERY

The word/phrase "every" or "for every".

Skip Distance Examples

A repeating 30 minute window starting 2 hours ago and repeating every hour until
now. This would result in 2 30-minute wide windows: 2 hours ago and 1 hour ago

Inclusion and Exclusion specifiers operate as filters on the set of windows. They
operate on the window beginning timestamp.

For inclusion specifiers, windows that are passed by any of the set of inclusion specifiers are included. Similarly, windows that
are passed by any of the set of exclusion specifiers
are excluded. Exclusion specifiers trump inclusion specifiers.

Specifiers follow one of the following formats depending on if it is an inclusion or
exclusion specifier:

INCLUSION specifier, specifier, ...

INCLUSION can be "include", "includes" or "including"

EXCLUSION specifier, specifier, ...

EXCLUSION can be "exclude", "excludes" or "excluding"

The specifiers are a set of fixed specifiers available as part of the language:

Fixed day of week-based specifiers - includes or excludes if the window is on the
specified day of the week

"monday" or "mondays"

"tuesday" or "tuesdays"

"wednesday" or "wednesdays"

"thursday" or "thursdays"

"friday" or "fridays"

"saturday" or "saturdays"

"sunday" or "sundays"

"weekday" or "weekdays"

"weekend" or ""weekends"

Relative day of week-based specifiers - includes or excludes based on the day of
week relative to now

"current day of the week"

"current day of week"

"this day of the week"

"this day of week"

Specified date - includes or excludes based on the specified date

"date" - Takes up to 2 arguments

The day in yyyy/MM/dd format if no second argument is
provided

Example: date:2017/12/25 would include or exclude December
25, 2017

(optional) The format in which to specify the first argument

Example: date:20171225:yyyyMMdd would include or exclude
December 25, 2017

Holidays - includes or excludes based on if the window starts during a
holiday

"holiday" or "holidays"

Arguments form the jollyday hierarchy of holidays. For example, "us:nyc" would be
holidays for New York City, USA.