Skip to content

Timestamps and durations#

CEL handles timestamps and durations natively. Extract components, measure elapsed time, and enforce time-based rules. Examples on this page use this message:

{
    "name": "Alice",
    "roles": ["admin", "editor", "viewer"],
    "age": 30,
    "email": "alice@example.com",
    "created": timestamp("2025-12-14T00:00:00Z"),
    "email_verified": timestamp("2025-12-14T18:30:00Z")
}

Extracting components#

getFullYear(), getMonth(), getDayOfMonth(), and getHours() extract individual parts of a timestamp.

user.created.getFullYear()
// result: 2025 (int)

user.created.getMonth()
// result: 11 (int)

Months are zero-indexed: January is 0, December is 11.

user.created.getDayOfMonth()
// result: 14 (int)

user.email_verified.getHours()
// result: 18 (int)

Duration comparisons#

Subtract two timestamps to get a duration, then compare.

user.email_verified - user.created
// result: 18h30m0s (google.protobuf.Duration)

Did the user verify their email within 24 hours of signing up?

user.email_verified - user.created < duration("24h")
// result: true (bool)

A stricter check (within 1 hour) fails.

user.email_verified - user.created < duration("1h")
// result: false (bool)

Timestamp arithmetic#

Add a duration to a timestamp to compute a future date.

user.created + duration("720h")
// result: 2026-01-13T00:00:00Z (google.protobuf.Timestamp)

CEL durations support hours, minutes, seconds, milliseconds, microseconds, and nanoseconds. There is no day or month unit. Use "720h" for 30 days and "8760h" for 365 days.

Time-based rules#

Check whether a timestamp falls in a specific year.

user.created.getFullYear() == 2025
// result: true (bool)

Check whether verification happened during business hours (9 AM to 5 PM UTC).

user.email_verified.getHours() >= 9 && user.email_verified.getHours() < 17
// result: false (bool)

The user verified at 18:30 UTC, outside the 9-17 window.

See also#

  • Time - Timestamp construction, timezone handling, duration components, and numeric conversions
  • Arithmetic operators - Numeric arithmetic and operator precedence
  • At a glance - Every function, macro, and operator