Time ranges

The Niagara Analytics Framework supports three types of time ranges; constants, absolute ranges and scripts.

Constants

These pre-defined values can be used to quickly process requests that involve standard time ranges:

all
today
yesterday
thisWeek
lastWeek
thisMonth
lastMonth
thisYear
lastYear
weekToDate
monthToDate
yearToDate

Absolute ranges

An absolute time range consists of two ISO 8601 ranges separated by a semi-column. The individual format of each is:

yyyy-mm-ddThh:mm:ss.mmm[+/-]hh:mm

where

Absolute element	Description
`yyyy-mm-dd`	Defines the date on which to begin the time range.
T	Identifies what follows as defining hours, minutes and seconds.
`hh:mm:ss`	Defines hours minutes and seconds.
`mmm`
[+/-]`hh:mm`	Specifies an offset number of hours and minutes to add to or subtract from the previously defined date and time.

The offset can be replaced with Z for UTC (Coordinated Universal Time, which is the current local time). The above is the format that BAbsTime uses for encoding/decoding.

For example:

2011-01-01T00:00:00-05:00;2012-12-31T23:59:59-05:00

starts the time range on December 31, 2010 at 7 pm. and ends it on December 31, 2011 at 6:59 pm.

2011-01-01T00:00:00Z;2012-12-31T23:59:59Z

starts the time range on January 1, 2011 offset into the future by the UTC; and ends the time range on December 31, 2012 at 11:59 pm offset into the future by the UTC.

Scripts

As with an absolute time range, a time range script allows you to apply any conceivable time range to a request, for example, a day’s worth of data for Sunday of last week, or data from the first 13 minutes of the last hour, etc. The advantage of a script over an absolute time range is that a script is relative to the current time. With a script, when you visit the same chart or table next month, the system automatically updates the time range to show the latest information. If you specify an absolute time range, you have to manually modify the dates each time you access a chart in order to view the latest information.

A script adheres to the following syntax:

from<unit><unitOffset>To<duration>

where

Script element	Option	Description
from	required syntax, is case sensitive	This keyword indicates that what immediately follows configures the start of the time range.
<unit>	Seconds, Minutes, Hours, Days, Weeks, Months, Years (case sensitive)	Sets the alignment of the data origin to a current period. For example, fromYear sets the alignment to the start of the current year; fromMinute sets the alignment to the start of the current minute.
<unitOffset>	<- or +P or P><#Y><#M><#D>T<#H><#M><#S>	Specifies an offset amount to subtract from (-) or add to (+) the `<unit>` to establish the start of the time range. For details, see unitOffset.
To	required syntax; is case sensitive.	This keyword separates the two parts of the time range and indicates that what follows configures the end of the time range.
<duration>	<Now> or <durationOffset>	Establishes the end date and time for the time range based on the start date and time. For details, see durationOffset.

unitOffset

Specifies an offset amount to apply to the <unit> to establish the start of the time range. The syntax of a unit offset is as follows:

<sign>P<#Y><#M><#D>T<#H><#M><#S>

unitOffset element	Value	Description
<sign>	plus (+) or minus (-)	Minus (-) subtracts from `<unit>, which moves` the beginning of the time range into the past. Plus (+) adds to `<unit>`, which moves the beginning of the time range into the future. P and +P are equivalent.
P	required case-sensitive letter	Begins the definition of the offset to apply to `<unit>` in terms of years, months and days.
<#Y><#M><#D>	optional year, month and day definitions	Defines a number of year(s), month(s), day(s) (case sensitive) to subtract from or add to `<unit>`.
T	case-sensitive letter (required if you are using <#H><#M><#S> and optional if you are using only <#Y><#M><#D)	Begins the definition of the offset in terms of hours, minutes and seconds.
<#H><#M><#S>	optional hours, minutes and seconds definitions	Defines an amount of time in hours, minutes and/or seconds (case sensitive) to subtract from or add to the `<unit>`.

durationOffset

Defines the duration of the time range in relationship to the start of the range. The syntax of a unit offset is:

<Now>

<P><#Y><#M><#D>T<#H><#M><#S>

The system calculates the duration by adding these values to the start of the time range. <durationOffset> cannot be negative.

durationOffset element	Value	Description
<Now>	case-sensitive keyword	Defines the current date and time as the `<duration>` (end of the time range). If you use `<Now>`, do not specify a `<durationOffset>`.
P	required case-sensitive letter	Begins the definition of the offset in terms of years, months and days. This designator is required even if you if are using only <#H><#M><#S>.
<#Y><#M><#D>	optional year, month and day definitions	Defines a number of year(s), month(s), day(s) (case sensitive) to add to the start time range. These are optional if you are using only <#H><#M><#S>.
T	case-sensitive letter (required if you are using <#H><#M><#S> and optional if you are using only <#Y><#M><#D)	Is required if you are using <#H><#M><#S> and optional if you are using only <#Y><#M><#D>.
<#H><#M><#S>	optional hours, minutes and seconds definitions	Defines an amount of time in hours minutes and seconds (case sensitive) to add to the start of the time range.

NOTE: Case is important. Always use uppercase when building an offset. For example, -P1Y2M3DT4H5M6S works; -p1y2m3dt4h5m6s does not work. Always include the P in front of <#Y><#M><#D>; and include the T in front of <#H><#M><#S>. You are not required to supply offset elements that are zero. For example, -P0Y0M5D is the same as -P5D.

Examples

Depending on the current date, this first example sets up a time range greater than one year. The actual range depends on the current date and time.

Start time: one year before the start of the current year (this year)
End time: now