Date range grammar

In order to make filtering by dates and date ranges easier on the end-user, Vizydrop uses a custom domain specific language to represent dates and date ranges. The syntax allows a user to specify either a static date or a dynamic date range using plain English statements.

Arbitrary Dates

Dates can be easily and quickly specified without any knowledge of the DSL by simply inserting a date in either DD-MMMM-YYYY, DD MMMM YYYY, DD-MM-YYYY or DD MM YYYY format.

The Date Spec DSL also includes various keyword elements that can be used to quickly insert dynamic values. In your date specification you may specify today and yesterday to get the appropriate date value. These date values will always parse in relation to the current day, allowing you to specify a date or date range of, or relative to, these dates.

Periods

Periods in the date spec DSL is where the majority of the magic happens. The DSL understands various time periods, as outlined in the chart below. These time periods can be referenced either aligned to their appropriate boundaries (calendar months, full weeks, quarters, etc.) or arbitrarily aligned to a particular day (the past month, past week, etc.).

PeriodAligned valueArbitrary value
daya daya day
weekiso week (Mon - Sun)7 days
monthcalendar month (1st day start)30 days
quartercalendar quarter (Q1, Q2, etc.)90 days
yearcalendar year (Jan 1 - Dec 31)365 days

Grammar usage

Periods can be referenced, as mentioned earlier, either aligned to an appropriate date boundary or arbitrarily aligned. When using an aligned period, the period fits to the calendar representation of that period. For example, an aligned month starts on the 1st day and ends on the last, whereas an arbitrary month would represent 30 days starting or ending on a particular day.

LAST and THIS statements

The last keyword creates a period aligned to the last period represented. Consider the following examples:

DSL statementvalue
last weekthe last full calendar week starting from Monday
last month` | the last full month, starting from the 1st
last quarterthe last full quarter
last yearthe last full year

User can specify period interval exactly. For example, last 3 weeks, last 8 months and etc. this keyword is an alias for last and can be used instead of it.

PREVIOUS statement

The previous keyword creates a range whose starts with first day of the period before the current period and continues for period length. Consider the following examples:

DSL statementvalue
previous weekstarts at 12:00:00 AM on the first day of the week before the current week and continues for seven days
previous monthstarts at 12:00:00 AM on the first day of the month before the current month and continues for all the days of that month
previous quarterstarts at 12:00:00 AM on the first day of the calendar quarter before the current calendar quarter and continues to the end of that quarter
previous yearstarts at 12:00:00 AM on January 1 of the year before the current year and continues through the end of December 31 of that year

User can specify period interval exactly. For example, previous 3 weeks, previous 8 months and etc.

BETWEEN statements

The between keyword allows you to specify a date range or minimum and maximum values to filter on with more power and precision. The full format for this statement is BETWEEN date AND date where both dates are some representation of a date (this can be an arbitrary date, keyword or period). ago keyword can be used inside between to specify date more precisely.

Consider the following examples:

DSL statementvalue
between 6 quarters ago and 2 months agostarts at 12:00:00 AM on the first day of the calendar quarter 6 quarters before the current calendar quarter and continues until to the first day of the calendar month 2 months before the current calendar month
between 1 January 2016 and todaybetween Jan 1, 2013 and today

FROM and TO statements

from and to allow user to specify ranges without minimum or maximum values.

Consider the following examples:

DSL statementvalue
from 1 Jan 2010starts at 1 Jan 2010 till now
to 1 Jan 2012ends with 1 Jan 2012

Receiving Parsed Dates

The date range grammar parses an input date with each use of a filter that utilizes a date-type field. These dates are provided to application connectors as a dictionary object representing a date range. User-input dates and date ranges are timezone-naive.

Date always will be parsed as date range. Even if user enters a single date in a field, this date will be parsed and further represented as a dictionary object with _min equal to start of the date and _max equal to end of the date. If a user enters a date range with no defined minimum or maximum, such as would be the case when using the FROM or TO keywords, _min and _max keys will not be present and the dictionary will have only _min or _max as its single key-value pair.

_min and _max represented as a string in ISO-8601 format.