Cloudera Docs » 1.2.1 » Analytics
Analytics
Also available as:
PDF

​Profile Selector Language

The domain specific language for the profile selector can be broken into a series of clauses, some of which are optional:

Total Temporal Duration

The total range of time in which windows may be specified

Temporal Window Width

The size of each temporal window

Skip distance

(optional) How far to skip between when one window starts and when the next begins

Inclusion/Exclusion specifiers

(optional) The set of specifiers to further filter the window

You must specify either a total temporal duration or a temporal window width. The remaining clauses are optional.

From a high level, the domain specific language fits the following three forms, which are composed of the clauses above:

  • time_interval Window (INCLUDING specifier list) (EXCLUDING specifier list)

    temporal window width inclusion specifiers exclusion specifier

  • time_interval WINDOW EVERY time_interval FROM time_interval (TO time_interval) (INCLUDING specifier_list) (EXCLUDING specifier list)

    temporal window width skip distance total temporal duration inclusion specifiers exclusion specifier

  • FROM time_interval (TO time_interval)

    total temporal duration total temporal duration

Total Temporal Duration

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

    • 30 minute window every 1 hour starting from 2 hours ago

      temporal window width skip distance total temporal duration

    • 30 minutes window every 1 hour from 2 hours ago

      temporal window width skip distance total temporal duration

  • A repeating 30 minute window starting 2 hours ago and repeating every hour until 30 minutes ago. 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 until 30 minutes ago

      temporal window width skip distance total temporal duration

    • 30 minutes window every 1 hour from 2 hours ago to 30 minutes ago

      temporal window width skip distance total temporal duration

    • 30 minutes window for every 1 hour from 30 minutes ago to 2 hours ago

      temporal window width skip distance total temporal duration

Inclusion/Exclusion Specifiers

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.

        Countries supported are those supported in jollyday

        Example: holiday:us:nyc would be the holidays of New York City, USA

      • If none is specified, it will choose based on locale.

        Example: holiday:hu would be the holidays of Hungary

Inclusion/Exclusion Specifiers Examples

The following are inclusion/exclusion specifier examples and identify the various clauses used in these examples.

Assume the following examples are executed at noon.

  • A 1 hour window for the past 8 'current day of the week'

    • 1 hour window every 24 hours from 56 days ago including this day of the week

      temporal window width skip distance total temporal duration inclusion/exclusion specifiers

  • A 1 hour window for the past 8 tuesdays

    • 1 hour window every 24 hours from 56 days ago including tuesdays

      temporal window width skip distance total temporal duration inclusion/exclusion specifiers

  • A 30 minute window every tuesday at noon starting 14 days ago until now

    • 30 minute window every 24 hours from 14 days ago including tuesdays

      temporal window width skip distance total temporal duration inclusion/exclusion specifiers

  • A 30 minute window every day except holidays and weekends at noon starting 14 days ago until now

    • 30 minutes every 24 hours from 14 days ago excluding holidays:us, weekends

      30 minutes every 24 hours from 14 days ago including weekdays excluding holidays:us, weekends

      temporal window width skip distance total temporal duration inclusion/exclusion specifiers

  • A 30 minute window at noon every day from 7 days ago including saturdays and excluding weekends. Because exclusions trump inclusions, the following will never yield any windows

    • 30 minute window every 24 hours from 7 days ago including saturdays excluding weekends

      temporal window width skip distance total temporal duration inclusion/exclusion specifiers

© 2012–2020, Cloudera, Inc.
Document licensed under the Creative Commons Attribution ShareAlike 4.0 License.
Cloudera.com | Documentation | Support | Community