Durations
Learn how to represent time spans in CQL.
In CQL, you can use durations to represent time spans in a human-readable way. Duration expressions are useful for performing calculations involving dates and times, like adding or subtracting time spans from dates.
A duration expression is a number followed by a unit, like you would say in natural language. For example, 1 day represents a duration of one day, and 2 hours represents a duration of two hours.
You can also use positive and negative numbers. For example, -1 day represents a time span of one day in the past, while +2 hours represents a time span of two hours in the future.
Time units
CQL supports a variety of time units, from nanoseconds to years, plus some special units like weekdays and weekend days.
The following table summarizes the behavior of each unit:
| Unit | Notes |
|---|---|
| Year | If the current date is February 29 and the target year is not a leap year, the resulting date is February 28. |
| Month | If the current day of the month exceeds the number of days in the target month, the resulting date is the last day of the target month. |
| Week | A week is equivalent to 7 days. |
| Week day | A weekday refers to a working day, as defined by the locale configured at the application level. |
| Weekend day | A weekend day refers to non-working days, as defined by the locale configured at the application level. |
| Day | Any day, including weekend days and weekdays. During daylight saving time shifts, the first occurrence of a time is used if it happens twice. If an hour is skipped, the time right after the jump is used. |
| Hour | An hour is defined as 60 minutes. |
| Minute | A minute is defined as 60 seconds. |
| Second | A second is defined as 1000 milliseconds. |
| Millisecond | A millisecond is defined as 1000 microseconds. |
| Microsecond | A microsecond is defined as 1000 nanoseconds. |
| Nanosecond | The smallest supported unit. |
It is important to note that days, weekdays and weekend days are three different concepts. While the day unit represents any day, weekdays and weekend days denote specific days of the week depending on the locale. This distinction is particularly useful for calculating shipping times and other calculations that depend on business days.
Variations
You can use singular and plural forms interchangeably, regardless of the numerical value. For example, both 1 day and 1 days are valid and equivalent, even though only the former is grammatically correct.
These are the supported variations for each unit:
- years, year
- months, month
- weeks, week
- weekdays, weekday
- weekend days, weekend day
- days, day
- hours, hour
- minutes, minute
- seconds, second
- milliseconds, millisecond, millis, milli
- microseconds, microsecond, micros, micro
- nanoseconds, nanosecond, nanos, nano
There is no difference between using the singular, plural, or abbreviated forms of a unit. These variations are provided for convenience and readability, so you can use whichever form you prefer.
Localization
When performing calculations involving durations, CQL takes into account the locale configured at the application level. This setting defines which days of the week are considered weekdays and which are weekend days.
Suppose the application is configured with a locale where Saturday and Sunday are considered the weekend days. If today is Friday and you add one weekday, the resulting date will be the following Monday, not Saturday, which would be the result if you added one day. Similarly, if you add one weekend day, the resulting date will be the following Sunday, not Saturday.
This feature allows you to perform complex calculations involving dates and times in a natural way. For example, the following expression calculates the 5th business day from today:
today plus 5 weekdays
You can also calculate past dates by subtracting durations. For example, the following expression calculates the date 3 months ago:
today minus 3 months
For more details on how date and time operations work, see the documentation on temporal arithmetic.