Temporal expressions
You can use the following FEEL temporal expressions. Examples are provided to show common use cases.
Literal
Creates a new temporal value. A value can be written in one of the following ways:
- using a temporal function (for example,
date("2020-04-06")) - using the
@- notation (for example,@"2020-04-06")
date("2020-04-06")
@"2020-04-06"
time("08:00:00")
time("08:00:00+02:00")
time("08:00:00@Europe/Berlin")
@"08:00:00"
@"08:00:00+02:00"
@"08:00:00@Europe/Berlin"
date and time("2020-04-06T08:00:00")
date and time("2020-04-06T08:00:00+02:00")
date and time("2020-04-06T08:00:00@Europe/Berlin")
@"2020-04-06T08:00:00"
@"2020-04-06T08:00:00+02:00"
@"2020-04-06T08:00:00@Europe/Berlin"
duration("P5D")
duration("PT6H")
@"P5D"
@"PT6H"
duration("P1Y6M")
duration("P3M")
@"P1Y6M"
@"P3M"
The value is null if a date or date-time literal doesn't represent a valid calendar date. For example, @"2024-06-31" is invalid because June has only 30 days.
Addition
Adds a value to another value. The operator is defined for the following types.
If a value has a different type, the result is null.
| First argument | Second argument | Result |
|---|---|---|
| date | duration | date |
| time | days-time-duration | time |
| date-time | duration | date-time |
| duration | date | date |
| duration | time | time |
| duration | date-time | date-time |
| duration | duration | duration |
date("2020-04-06") + duration("P1D")
// date("2020-04-07")
time("08:00:00") + duration("PT1H")
// time("09:00:00")
date and time("2020-04-06T08:00:00") + duration("P7D")
// date and time("2020-04-13T08:00:00")
duration("P2D") + duration("P5D")
// duration("P7D")
Subtraction
Subtracts a value from another value. The operator is defined for the following types.
If a value has a different type, the result is null.
If one value has a timezone or time-offset, the other value must have a timezone or time-offset too. Otherwise, the result is null.
| First argument | Second argument | Result |
|---|---|---|
| date | date | days-time-duration |
| date | duration | date |
| time | time | days-time-duration |
| time | days-time-duration | time |
| date-time | date-time | days-time-duration |
| date-time | duration | date-time |
| days-time-duration | days-time-duration | days-time-duration |
| years-months-duration | years-months-duration | years-months-duration |
date("2020-04-06") - date("2020-04-01")
// duration("P5D")
date("2020-04-06") - duration("P5D")
// date("2020-04-01")
time("08:00:00") - time("06:00:00")
// duration("PT2H")
time("08:00:00") - duration("PT2H")
// time("06:00:00")
duration("P7D") - duration("P2D")
// duration("P5D")
duration("P1Y") - duration("P3M")
// duration("P9M")
Multiplication
Multiplies a value by another value. The operator is defined for the following types.
If a value has a different type, the result is null.
| First argument | Second argument | Result |
|---|---|---|
| days-time-duration | number | days-time-duration |
| number | days-time-duration | days-time-duration |
| years-months-duration | number | years-months-duration |
| number | years-months-duration | years-months-duration |
duration("P1D") * 5
// duration("P5D")
duration("P1M") * 6
// duration("P6M")
Division
Divides a value by another value. The operator is defined for the following types.
If a value has a different type, the result is null.
| First argument | Second argument | Result |
|---|---|---|
| days-time-duration | days-time-duration | number |
| days-time-duration | number | days-time-duration |
| years-months-duration | years-months-duration | number |
| years-months-duration | number | years-months-duration |
duration("P5D") / duration("P1D")
// 5
duration("P5D") / 5
// duration("P1D")
duration("P1Y") / duration("P1M")
// 12
duration("P1Y") / 12
// duration("P1M")
Properties
A temporal value has multiple properties for its components. The following properties are available for the given types:
| Property | Available for | Description |
|---|---|---|
| year | date, date-time | the year as number |
| month | date, date-time | the month as number [1..12], where 1 is January |
| day | date, date-time | the day of the month as number [1..31] |
| weekday | date, date-time | the day of the week as number [1..7], where 1 is Monday |
| hour | time, date-time | the hour of the day as number [0..23] |
| minute | time, date-time | the minute of the hour as number [0..59] |
| second | time, date-time | the second of the minute as number [0..59] |
| time offset | time, date-time | the duration offset corresponding to the timezone or null |
| timezone | time, date-time | the timezone identifier or null |
| days | days-time-duration | the normalized days component as number |
| hours | days-time-duration | the normalized hours component as number [0..23] |
| minutes | days-time-duration | the normalized minutes component as number [0..59] |
| seconds | days-time-duration | the normalized seconds component as number [0..59] |
| years | years-months-duration | the normalized years component as number |
| months | years-months-duration | the normalized months component as number [0..11] |
date("2020-04-06").year
// 2020
date("2020-04-06").month
// 4
date("2020-04-06").weekday
// 1
time("08:00:00").hour
// 8
date and time("2020-04-06T08:00:00+02:00").time offset
// duration("PT2H")
date and time("2020-04-06T08:00:00@Europe/Berlin").timezone
// "Europe/Berlin"
duration("PT2H30M").hours
// 2
duration("PT2H30M").minutes
// 30
duration("P6M").months
// 6
Examples
Compare date with offset
Check if a date is at least 6 months before another date.
date1 < date2 + @"P6M"
Calculate age
Return the current age of a person based on a given birthday.
years and months duration(date(birthday), today()).years
Check for weekend
Check if the current day is on a weekend.
day of week(today()) in ("Saturday","Sunday")
Calculate duration between dates
Return the duration between now and the next Tuesday at 08:00.
(for x in 1..7
return date and time(today(),@"08:00:00Z") + @"P1D" * x
)[day of week(item) = "Tuesday"][1] - now()
Calculate duration between times
Return the duration between now and the next time it is 09:00 in the Europe/Berlin timezone.
{
time: @"09:00:00@Europe/Berlin",
date: if time(now()) < time then today() else today() + @"P1D",
duration: date and time(date, time) - now()
}.duration
Calculate next weekday
Return the next day that is not a weekend at 00:00.
(for x in 1..3
return date and time(today(),@"00:00:00Z") + @"P1D" * x
)[not(day of week(item) in ("Saturday","Sunday"))][1]
Change format of dates
Transform a given list of date-time values into a custom format.
for d in dates return {
date: date(date and time(d)),
day: string(date.day),
month: substring(month of year(date), 1, 3),
year: string(date.year),
formatted: day + "-" + month + "-" + year
}.formatted
Evaluation context
["2021-04-21T07:25:06.000Z", "2021-04-22T07:25:06.000Z"]
Evaluation result
["21-Apr-2021", "22-Apr-2021"]
Create a Unix timestamp
Return the current point in time as a Unix timestamp.
(now() - @"1970-01-01T00:00Z") / @"PT1S" * 1000
Evaluation result
1618200039000