Time#

CEL supports timestamps and durations for working with time. These correspond to google.protobuf.Timestamp and google.protobuf.Duration.

Timestamps#

Create a timestamp from an RFC 3339 string using the timestamp() function.

timestamp("2024-01-15T10:30:45.123Z")
// result: 2024-01-15T10:30:45.123Z (google.protobuf.Timestamp)

Timestamp components#

Extract date and time components from a timestamp. All methods return values in UTC by default.

timestamp("2024-01-15T10:30:45.123Z").getFullYear()
// result: 2024 (int)

timestamp("2024-01-15T10:30:45.123Z").getHours()
// result: 10 (int)

timestamp("2024-01-15T10:30:45.123Z").getMinutes()
// result: 30 (int)

timestamp("2024-01-15T10:30:45.123Z").getSeconds()
// result: 45 (int)

Days and month components are zero-indexed (0 = Sunday/January).

// getDayOfWeek() is zero-indexed: Monday, January 15, 2024 returns 1.
timestamp("2024-01-15T10:30:45.123Z").getDayOfWeek()
// result: 1 (int)

// getDayOfMonth() is zero-indexed: January 15th returns 14.
timestamp("2024-01-15T10:30:45.123Z").getDayOfMonth()
// result: 14 (int)

// getDayOfYear() is zero-indexed: January 15th returns 14.
timestamp("2024-01-15T10:30:45.123Z").getDayOfYear()
// result: 14 (int)

// getMonth() is zero-indexed: January returns 0.
timestamp("2024-01-15T10:30:45.123Z").getMonth()
// result: 0 (int)

Timezones#

Pass a timezone string to extract components in a specific timezone. Timezones use IANA timezone names.

timestamp("2024-01-15T10:30:45.123Z").getHours("America/New_York")
// result: 5 (int)

All component extraction methods accept an optional timezone argument: getFullYear(), getMonth(), getDayOfMonth(), getDayOfWeek(), getDayOfYear(), getHours(), getMinutes(), and getSeconds().

Invalid timezone names produce a runtime error.

timestamp("2024-01-15T10:30:45.123Z").getHours("Invalid/Timezone")
// error: unknown time zone Invalid/Timezone

Durations#

Create a duration from a string with unit suffixes using the duration() function. Supported units: h (hours), m (minutes), s (seconds), ms (milliseconds), us (microseconds), ns (nanoseconds).

duration("1h30m")
// result: 1h30m0s (google.protobuf.Duration)

duration("-500ms")
// result: -500ms (google.protobuf.Duration)

duration(string(3600) + "s")
// result: 1h0m0s (google.protobuf.Duration)

Duration components#

Extract the total value in a specific unit.

duration("1h30m").getHours()
// result: 1 (int)

duration("-1h30m").getMinutes()
// result: -90 (int)

duration("90s").getSeconds()
// result: 90 (int)

duration("1500ms").getMilliseconds()
// result: 1500 (int)

Values smaller than the requested unit return zero.

duration("30m").getHours()
// result: 0 (int)

Arithmetic#

Add or subtract a duration from a timestamp.

timestamp("2024-01-15T10:30:45.123Z") + duration("1h")
// result: 2024-01-15T11:30:45.123Z (google.protobuf.Timestamp)

timestamp("2024-01-15T10:30:45.123Z") - duration("30m")
// result: 2024-01-15T10:00:45.123Z (google.protobuf.Timestamp)

Subtract two timestamps to get a duration.

timestamp("2024-01-15T11:30:45.123Z") - timestamp("2024-01-15T10:30:45.123Z")
// result: 1h0m0s (google.protobuf.Duration)

Add or subtract durations.

duration("1h") + duration("30m")
// result: 1h30m0s (google.protobuf.Duration)

duration("2h") - duration("30m")
// result: 1h30m0s (google.protobuf.Duration)

Numeric conversions#

Convert a timestamp to Unix epoch seconds.

int(timestamp("2024-01-15T10:30:45Z"))
// result: 1705314645 (int)

Convert a duration to nanoseconds.

int(duration("1h"))
// result: 3600000000000 (int)