Interval Structures

An interval structure is an expression that represents an interval of elapsed time.

Syntax

intervalStructure : INTERVAL '{' component (',' component)* '}' ;

component : durationUnit ':' multiplier;

durationUnit : DAYS | HOURS | MINUTES | SECONDS | MILLISECONDS;

multiplier : expression;

Quick Look

Return the rental events with timestamps that are more than 5 and a half days old:

`FROM RentalEvents WHERE ($$NOW - timestamp) > INTERVAL{DAYS:5, HOURS:12} RETURN *;`

Update a rental event with the elapsed time between the reserved pickup time and the actual pick up time:

`UPDATE PickUp WHERE $$ID == 3-3-1-129 SET delta TO INTERVAL{HOURS: 48};`

Discussion

An interval structure is an expression whose components combine to represent an interval of elapsed time, also called a timespan or duration. For example, the following interval structure represents a positive interval of time whose length is 3 days, 22 hours, 17 minutes, 49 seconds, and 350 milliseconds:

INTERVAL{DAYS: 3, HOURS: 22, MINUTES: 17, SECONDS: 49, MILLISECONDS: 350}

An interval structure can represent a negative interval of time, as well—for example:

INTERVAL{DAYS: -3, HOURS: -22, MINUTES: -17, SECONDS: -49, MILLISECONDS: -350}

An interval structure can represent timespans ranging from 5,000,000 days to -5,000,000 days.

Specifying Interval Components

You specify an interval structure as a list of one or more component expressions, where each component consists of a durationUnit and a multiplier, separated by a colon:

■A durationUnit is a keyword that describes a common interval of a particular length (a day, hour, minute, second, or millisecond). Days are the largest unit used for measuring duration, because the larger units (such as months and years) vary in length.

■A multiplier is an expression that evaluates to a number, which is typically a positive or negative integer, but could be fractional.

DO permits you to specify the component expressions of an interval structure in a variety of ways:

■You do not need to include a component expression for every durationUnit; rather, you can choose just the ones that best represent the interval you want to specify. (Omitting a component for a particular durationUnit is equivalent to specifying that durationUnit with a multiplier of 0.) For example:

INTERVAL{HOURS: 3, MILLISECONDS:48}

■You can specify multipliers that are expressions for calculating a duration. For example:

INTERVAL{SECONDS: (60*30)}

■You can specify a multiplier that exceeds the normal limit for the corresponding durationUnit. For example:

INTERVAL{HOURS: 36}

■You can specify fractional multipliers. For example:

INTERVAL{DAYS: 1.5}

■You can mix positive and negative multipliers. (The represented interval is always either positive or negative.) For example:

INTERVAL{DAYS: 1, HOURS: -2}

Ticks and Normalized Interval Components

Each durationUnit is a shorthand for a specific number of ticks, where a tick equals 100 nanoseconds. For example, MINUTES stands for the number of ticks in a minute. The duration represented by an individual component is equal to the multiplier times the number of ticks in the durationUnit. An interval structure therefore evaluates to the total number of ticks specified by all of its individual component expressions combined.

The use of ticks enables DO to interpret interval components in a consistent way, no matter how you specify them. Furthermore, when DO returns an interval value, the interval is represented as a list of normalized components, as described in the following table:

Component in a Returned Interval | Normalized Component Value |

DAY: n | Number of whole days |

HOURS: n | Number of whole hours after days are subtracted—an integer from 0 to 23. |

MINUTES: n | Number of whole minutes after hours are subtracted—an integer from 0 to 59. |

SECONDS: n | Number of whole seconds after minutes are subtracted—an integer from 0 to 59. |

MILLISECONDS: n | Number of whole milliseconds after seconds are subtracted—an integer from 0 to 999. |

Here are some sample interval structures and their normalized equivalents:

Specified Interval Structure | Equivalent Normalized Interval |

INTERVAL{HOURS: 36} | INTERVAL{DAY: 1, HOURS: 12} |

INTERVAL{SECONDS: (60*30)} | INTERVAL{MINUTES: 30} |

INTERVAL{DAYS: 1.5} | INTERVAL{DAY: 1, HOURS: 12} |

INTERVAL{DAYS: 1, HOURS: -2} | INTERVAL{HOURS: 22} |