Temporal functions ​

Temporal functions read, calculate with, and move between dates, times, instants, and durations. This is the largest category in the standard library. It's also where the most integration bugs live, such as a report that is off by one day, an SLA that fires an hour late twice a year, or a date that changes when it crosses a system boundary.

Pick the right type first ​

Most temporal bugs are a type choice, not a function choice. WEL separates an instant from a wall-clock reading, and the separation is what prevents the classic errors.

Read a component ​

These take a PlainDate, DateTime, or PlainDateTime and return one part of it.

year ​

Returns the year.

year(value)

year(PlainDate('2026-03-15'))

2026

month ​

Returns the month as a number from 1 to 12.

month(value)

month(PlainDate('2026-03-15'))

3

day ​

Returns the day of the month, from 1 to 31.

day(value)

day(PlainDate('2026-03-15'))

15

quarter ​

Returns the calendar quarter, from 1 to 4.

quarter(value)

quarter(PlainDate('2026-03-15'))

1

day_of_year ​

Returns the day of the year, from 1 to 366.

day_of_year(value)

day_of_year(PlainDate('2026-03-15'))

74

day_of_week ​

Returns the day of the week from 1 to 7, where 1 is the locale's first day of the week.

That makes the number locale-dependent: the same date is 1 where the week starts on Sunday and 7 where it starts on Monday. Prefer an explicit comparison against day_of_week_name, or confirm the recipe's locale, when the number is going into a destination system.

day_of_week(value)

day_of_week(PlainDate('2026-03-15'))

1

day_of_week_name ​

Returns the localized name of the day.

day_of_week_name(value)

day_of_week_name(PlainDate('2026-03-15'))

Sunday

month_name ​

Returns the localized name of the month.

month_name(value)

month_name(PlainDate('2026-03-15'))

March

hour ​

Returns the hour, from 0 to 23.

hour(value)

hour(DateTime('2026-03-15T09:30:45Z'))

9

minute ​

Returns the minute, from 0 to 59.

minute(value)

minute(DateTime('2026-03-15T09:30:45Z'))

30

second ​

Returns the second as a Decimal, so fractional precision is preserved.

second(value)

second(DateTime('2026-03-15T09:30:45Z'))

45

time ​

Returns the wall-clock time as a PlainTime. With a time zone argument, it returns the local time in that zone instead.

time(datetime, timezone)

time(DateTime('2026-03-15T09:30:45Z'))

09:30:45

time(DateTime('2026-03-15T09:30:45Z'), 'Asia/Tokyo')

18:30:45

to_map ​

Decomposes any temporal value, including Duration, into a map of its components.

to_map(value)

to_map(PlainDate('2026-03-15'))

{year: 2026, month: 3, day: 15}

to_map(Duration('PT2H30M'))

{hours: 2, minutes: 30, seconds: 0}

Calendar arithmetic ​

A calendar month and 30 days aren't the same increment. The difference shows up at the end of the month. These two functions handle that case differently.

add_months ​

Adds a number of months, clamping to the end of the month when the target has fewer days. Equivalent to the EDATE function in Excel.

January 31 plus one month is February 28, or 29 in a leap year. Use this when a business rule means "the same date next month, or the last day if there isn't one," which describes most billing and subscription rules.

add_months(date, months)

add_months(PlainDate('2026-01-31'), 1)

2026-02-28

add_months(PlainDate('2026-03-15'), -2)

2026-01-15

advance_date ​

Advances a PlainDate by any combination of years, months, and days.

advance_date raises an error rather than clamping when the result wouldn't be a real date, unlike add_months. Use it when an impossible date means the input was wrong and you would rather the job fail than silently move the day.

advance_date(date, delta)

advance_date(PlainDate('2026-03-15'), {days: 10})

2026-03-25

advance_date(PlainDate('2026-03-15'), {years: 1, months: 2})

2027-05-15

date_diff ​

Decomposes the gap between two dates into years, months, and days.

date_diff measures from the first date to the second, so a second date that is earlier gives negative components.

date_diff(from, to)

date_diff(PlainDate('2025-01-10'), PlainDate('2026-03-15'))

{years: 1, months: 2, days: 5}

date_diff(PlainDate('2026-03-15'), PlainDate('2025-01-10'))

{years: -1, months: -2, days: -5}

advance_datetime ​

Advances a DateTime by years, months, days, hours, minutes, or seconds, in a given time zone.

advance_datetime(datetime, delta, timezone, on_gap, on_fold)

advance_datetime(DateTime('2026-03-15T09:30:00Z'), {hours: 5})

2026-03-15T14:30:00Z

Duration arithmetic ​

The following functions add or subtract an ISO 8601 duration from a DateTime:

datetime_add_duration ​

Adds a duration, written as an ISO 8601 string, to a DateTime.

Clock-only durations such as PT2H preserve the offset. Calendar durations such as P1D apply in the given time zone, or the locale's, so that "one day later" stays the same wall-clock time across a daylight-saving change.

datetime_add_duration(datetime, duration, timezone, on_gap, on_fold)

datetime_add_duration(DateTime('2026-03-15T09:30:00Z'), 'PT2H')

2026-03-15T11:30:00Z

datetime_sub_duration ​

Subtracts a duration from a DateTime. Takes the same arguments as datetime_add_duration.

datetime_sub_duration(datetime, duration, timezone, on_gap, on_fold)

datetime_sub_duration(DateTime('2026-03-15T09:30:00Z'), 'P1D')

2026-03-14T09:30:00Z

Measure an interval ​

The following functions measure the interval between two instants, as a Duration:

until ​

Returns the signed duration from the first instant to the second.

until(from, to)

until(DateTime('2026-03-15T09:00:00Z'), DateTime('2026-03-15T11:30:00Z'))

PT2H30M

since ​

Returns the signed duration between two instants, taking the second from the first, the opposite argument order to until.

since(now(), created_at) matches how the question is normally phrased: "how long since it was created?"

since(later, earlier)

since(DateTime('2026-03-15T11:30:00Z'), DateTime('2026-03-15T09:00:00Z'))

PT2H30M

in_hours, in_minutes, in_seconds, in_days ​

Convert a Duration to a whole number of the named unit, truncating rather than rounding. PT150M is 2 hours, not 3.

in_days(duration)
in_hours(duration)
in_minutes(duration)
in_seconds(duration)

in_hours(Duration('PT150M'))

2

in_minutes(Duration('PT2H30M'))

150

in_seconds(Duration('PT1M30S'))

90

in_days(Duration('PT72H'))

3

Use case: Flag tickets past their SLA ​

A support queue needs tickets flagged once they've been open too long. Measure each ticket's age against now() and mark the ones over 48 hours:

Input

{
  "tickets": [
    {"id": "T-1", "created_at": "2026-07-09T08:00:00Z"},
    {"id": "T-2", "created_at": "2026-07-12T06:00:00Z"}
  ]
}

Formula

_.tickets >> map_by(t ~> {
  id: t.id,
  age_hours: in_hours(since(now(), DateTime(t.created_at))),
  breached: in_hours(since(now(), DateTime(t.created_at))) > 48
})

Output

[
  {"id": "T-1", "age_hours": 76, "breached": true},
  {"id": "T-2", "age_hours": 6, "breached": false}
]

This example uses now() at 2026-07-12T12:34:56.789Z. This formula always computes age_hours and breached from the same instant, so they can't disagree, because now() is fixed for the whole step.

Period boundaries ​

These snap a value to the start or end of a period, the usual way to build a reporting window or bucket records by month.

Each accepts no arguments for the current instant in UTC, one argument for a supplied value, or two for a DateTime and a time zone.

start_of_day and end_of_day ​

Return the first and last instant of the calendar day.

start_of_day(datetime)
end_of_day(datetime, timezone)

start_of_day(DateTime('2026-03-15T09:30:00Z'))

2026-03-15T00:00:00Z

end_of_day(DateTime('2026-03-15T09:30:00Z'))

2026-03-15T23:59:59.999999999Z

end_of_day is the last representable instant of the day, not the following midnight, so a <= comparison against it includes the whole day without also catching the next one.

start_of_hour ​

Returns the first instant of the hour.

start_of_hour(datetime, timezone)

start_of_hour(DateTime('2026-03-15T09:30:45Z'))

2026-03-15T09:00:00Z

start_of_week and end_of_week ​

These functions are locale-aware. Which day the week starts on depends on the recipe's locale.

start_of_week(value)
end_of_week(value, timezone)

start_of_week(PlainDate('2026-03-15'))

2026-03-15

end_of_week(PlainDate('2026-03-15'))

2026-03-21

start_of_month and end_of_month ​

Return the first and last day of the calendar month.

start_of_month(value)
end_of_month(value, timezone)

start_of_month(PlainDate('2026-03-15'))

2026-03-01

end_of_month(PlainDate('2026-03-15'))

2026-03-31

start_of_quarter and end_of_quarter ​

Return the first and last day of the calendar quarter.

start_of_quarter(value)
end_of_quarter(value, timezone)

start_of_quarter(PlainDate('2026-03-15'))

2026-01-01

end_of_quarter(PlainDate('2026-03-15'))

2026-03-31

start_of_year and end_of_year ​

Return the first and last day of the calendar year.

start_of_year(value)
end_of_year(value, timezone)

start_of_year(PlainDate('2026-03-15'))

2026-01-01

end_of_year(PlainDate('2026-03-15'))

2026-12-31

Use case: Build the current month's reporting window ​

A report needs the first and last day of the current calendar month. Build both from now() with start_of_month and end_of_month:

Input

{}

Formula

{
  from: start_of_month(PlainDate(now())),
  to: end_of_month(PlainDate(now()))
}

Output

{"from": "2026-07-01", "to": "2026-07-31"}

This example uses now() at 2026-07-12T12:34:56.789Z. Convert to PlainDate first: reporting APIs expect calendar dates, and an instant's day depends on the reader's zone.

Time zones ​

The following functions convert a DateTime between time zones and inspect its offset:

in_tz ​

Re-renders the same instant in another time zone. The instant doesn't change, only how it reads.

in_tz(datetime, timezone)

in_tz(DateTime('2026-03-15T09:30:00Z'), 'Asia/Tokyo')

2026-03-15T18:30:00+09:00

assume_tz ​

Interprets a PlainDateTime's wall-clock reading as occurring in a given time zone, producing a DateTime.

assume_tz is the opposite direction to in_tz. in_tz keeps the instant and changes the reading. assume_tz keeps the reading and determines the instant. Use it when a source system sends a local time and tells you the zone separately.

assume_tz(plain_datetime, timezone, on_gap, on_fold)

assume_tz(PlainDateTime('2026-03-15T09:30:00'), 'Europe/London')

2026-03-15T09:30:00Z

utc_offset ​

Returns the offset from UTC as a canonical string: Z, or a signed offset such as +02:00.

utc_offset(datetime)

utc_offset(DateTime('2026-03-15T09:30:00Z'))

Z

utc_offset(in_tz(DateTime('2026-07-15T09:30:00Z'), 'Asia/Tokyo'))

+09:00

is_dst? ​

Returns true if daylight saving time is in effect at that instant in that zone.

is_dst?(datetime, timezone)

is_dst?(DateTime('2026-07-15T09:30:00Z'), 'Europe/London')

true

is_dst?(DateTime('2026-01-15T09:30:00Z'), 'Europe/London')

false

observes_dst? ​

Returns true if the time zone observes daylight saving at all, in a given year.

observes_dst?(timezone)
observes_dst?(timezone, year)

observes_dst?('Europe/London')

true

observes_dst?('Asia/Tokyo')

false

Use case: Report events on the local business date ​

Two events on the same UTC day fall on different calendar dates in Tokyo. Convert to the local zone before taking the date, or the daily report will be wrong for everything after 15:00 UTC:

Input

{
  "events": [
    {"id": "E-1", "at": "2026-03-15T16:30:00Z"},
    {"id": "E-2", "at": "2026-03-15T09:30:00Z"}
  ]
}

Formula

_.events >> map_by(e ~> {
  id: e.id,
  tokyo_date: PlainDate(in_tz(DateTime(e.at), 'Asia/Tokyo'))
})

Output

[
  {"id": "E-1", "tokyo_date": "2026-03-16"},
  {"id": "E-2", "tokyo_date": "2026-03-15"}
]

E-1 moves to the 16th because 16:30 UTC is 01:30 the next morning in Tokyo. The raw UTC value's PlainDate would have reported both on the 15th instead.

Current instant and epoch time ​

The following functions read the current instant, or convert to and from Unix epoch seconds:

now ​

Returns the current instant with a UTC offset that's fixed for the whole step. It takes no arguments.

now()

epoch ​

Builds a DateTime from Unix epoch seconds.

epoch(seconds)

epoch(1773567000)

2026-03-15T09:30:00Z

to_epoch ​

Converts a DateTime to Unix epoch seconds, as a Decimal so nanosecond precision survives.

to_epoch(datetime)

to_epoch(DateTime('2026-03-15T09:30:00Z'))

1773567000

to_iso8601 ​

Formats a DateTime as ISO 8601 with its offset.

to_iso8601(datetime)

to_iso8601(DateTime('2026-03-15T09:30:00Z'))

2026-03-15T09:30:00Z

Related ​

• Conversion functions: How to construct each data type, such as DateTime, PlainDate, and Duration.
• Formatting functions: format_date, parse_datetime, to_rfc3339.
• Data types: More information about the temporal types.
• Error codes: Troubleshoot job failures such as E020 and E222.