Date Ranges

Date range periods operate over the range 1970-01-01 to 2050-01-01. They are start
date and end date inclusive.

Serializations

// "on"
{
  "type": "on",
  "date": "2017-01-15"
}

// "exactly"
{
  "type": "on",
  "date": "-P2D"
}

// "before"
{
  "type": "before",
  "date": "2017-01-15"
}

// "more than"
{
  "type": "before",
  "date": "-P2D"
}

// "after"
{
  "type": "after",
  "date": "2017-01-15"
}

// "less than"
{
  "type": "after",
  "date": "-P2D"
}

// "between" with two static dates
{
  "type": "between",
  "date": "2017-01-15/2017-01-16"
}

// "between" with two rolling dates
{
  "type": "between",
  "date": "-P5D/-PT48H"
}

// "between" with a static date and a rolling date
{
  "type": "between",
  "date": "2017-01-15/-P2D"
}

// "between" with a rolling date and a static date
{
  "type": "between",
  "date": "-P2D/2017-01-16"
}

// "between" with a future period
{
  "type": "between",
  "date": "-P5D/P4D"
}

// "last x days"
{
  "type": "preset",
  "preset": "last_7_days"
}

// "ever"
{
  "type": "preset",
  "preset": "ever"
}

// "today"
{
  "type": "preset",
  "preset": "today"
}

// "yesterday"
{
  "type": "preset",
  "preset": "yesterday"
}

// "this month to date"
{
  "type": "preset",
  "preset": "this_month_to_date"
}

Rolling Periods

Rolling date ranges change depending on the time they are run. A report run
at 2016-03-15T12:00:00Z with a range from 4 hours ago to now would effectively
be retrieving the range 2016-03-15T08:00:00Z to 2016-03-15T12:00:00Z, while the
same report run exactly 48 hours later would be querying over
2016-03-17T08:00:00Z to 2016-03-17T12:00:00Z. A static report's date range will
not change like this.

Exactly

The exactly option allows users to specify a rolling 24-hour period ending
some number of seconds ago. In the UI, users select an integer number of days
ago, but internally, we use seconds (days ago 24 hours/day 60 min/hour 60
sec/min = seconds ago or simply days ago 86400).

As an example, a user selecting "exactly 2 days ago" creates a rolling 24 hour
window from 72 hours ago to 48 hours ago.

This is serialized as:

{
  "date_range": {
    "type": "on",
    "date": "-P2D"
  }
}

More Than

The more than option allows users to specify an "unbounded", rolling period which
terminates a specified number of seconds ago. In the UI, users select an integer number of days
ago, but internally, we use seconds (days ago 24 hours/day 60 min/hour 60 sec/min = seconds ago or simply days ago 86400).

As an example, a user selecting "more than 2 days ago" creates a rolling window of time from 1970-01-01T00:00:00Z to 172,801 seconds ago.

This is serialized as:

{
  "date_range": {
    "type": "before",
    "date": "-P2D"
  }
}

Less Than

The less than option allows users to specify a rolling period bounded by a
specified number of seconds ago and the current time. In the UI, users select an integer number of days
ago, but internally, we use seconds (days ago 24 hours/day 60 min/hour 60 sec/min = seconds ago or simply days ago 86400).

As an example, a user selecting "less than 2 days ago" creates a rolling window of time from 172,799 seconds ago to 0 seconds ago.

This is serialized as:

{
  "date_range": {
    "type": "after",
    "date": "-P2D"
  }
}

Range

The between option allows users to specify two durations (or any combination of
durations and ISO8601 timestamps).

As an example, a user selecting "between 30-90 days ago"
creates a rolling period of time (-P90D/-P30D).

This is serialized as:

{
  "date_range": {
    "type": "between",
    "date": "-P90D/-P30D"
  }
}

Last X Days

The last X days preset allows users to specify a rolling period calendar-bounded by a
specified number of days ago and the end of yesterday.

As an example, a user selecting "last 7 days" creates a rolling window
of time from 7 days ago at the beginning of the day to 1 day ago at the end of the day.

We do not convert to seconds internally as this period is calendar bounded.

This is serialized as:

{
  "date_range": {
    "type": "preset",
    "preset": "last_7_days"
  }
}

Today

The today preset allows users to specify a rolling period calendar-bounded by the current day.

As an example, a user selecting "today" creates a rolling window
of time from 0 days ago at the beginning of the day to 0 days ago at the end of the day.

We do not convert to seconds internally as this period is calendar bounded.

This is serialized as:

{
  "date_range": {
    "type": "preset",
    "preset": "today"
  }
}

Yesterday

The yesterday preset allows users to specify a rolling period calendar-bounded by the previous day.

As an example, a user selecting "yesterday" creates a rolling window
of time from 1 day ago at the beginning of the day to 1 day ago at the end of the day.

We do not convert to seconds internally as this period is calendar bounded.

This is serialized as:

{
  "date_range": {
    "type": "preset",
    "preset": "yesterday"
  }
}

This month to date

The this_month_to_date preset allows users to specify a rolling period calendar-bounded
by the beginning of the month and the current day.

As an example, a user selecting "this_month_to_date" creates a rolling window
of time from 0 days ago at the beginning of the month to 1 day ago at the end of the day.

We do not convert to seconds internally as this period is calendar bounded.

This is serialized as:

{
  "date_range": {
    "type": "preset",
    "preset": "this_month_to_date"
  }
}

Static Periods

Unlike rolling date ranges, static date ranges are not dependent on the time
they are run, and they do not change. The same report run two hours apart will
always query over the same timestamps.

On

The on option allows users to specify a date, which becomes a bounded, static
period between 00:00:00 and 23:59:59 for that calendar date. In the UI, users
select a calendar date, but internally, we use full ISO8601 timestamps for the
range.

As an example, a user selecting "on 2016-12-24" creates a static period of time
from 2016-12-24T00:00:00Z to 2016-12-24T23:59:59Z.

This is serialized as:

{
  "date_range": {
    "type": "on",
    "date": "2016-12-24"
  }
}

Before

The before option allows users to specify a date, which becomes a
bounded, static period starting on 01-01-1970 and terminating at 23:59:59 on the
day before the specified calendar date. In the UI, users select a calendar date,
but internally, we use full ISO8601 timestamps for the range.

As an example, a user selecting "before 2016-12-24" creates a static period of
time from 1970-01-01T00:00:00Z to 2016-12-23T23:59:59Z.

This is serialized as (note that end date is exclusive):

{
  "date_range": {
    "type": "before",
    "date": "2016-12-24"
  }
}

After

The after option allows users to specify a date, which becomes a bounded period
beginning at midnight on the day after the specified calendar date and terminating
at the current time.

If a date of the form YYYY-MM-DD is passed, the start date will be at 00:00:00 on
the following day. However, if a time is provided, the start date will be at that exact time.

As an example, a user selecting "after 2016-12-24" on 2017-12-30 creates a static period of
time from 2016-12-25T00:00:00 to 2017-12-30T00:00:00.

This is serialized as:

{
  "date_range": {
    "type": "after",
    "date": "2016-12-24"
  }
}

Between

The between option allows users to specify two dates, which become
the bounds of a static period starting at midnight on the start date and ending
at 23:59:59 on the end date (assuming no time is provided). In the UI, users select two calendar dates.

As an example, a user selecting "between 2016-12-24 and 2017-01-02"
creates a static period of time from 2016-12-24T00:00:00Z to
2017-01-02T23:59:59Z.

This is serialized as:

{
  "date_range": {
    "type": "between",
    "date": "2016-12-24/2017-01-02"
  }
}

Ever

The ever option is basically all time. It is represented internally as
1970-01-01T00:00:00Z to 2050-01-01T00:00:00Z.

This is serialized as:

{
  "date_range": {
    "type": "preset",
    "preset": "ever"
  }
}