»Import: time

The time import provides access to the execution time and time functions.

During the execution of a policy the time is fixed to the moment of execution. This gives the illusion that a policy instantly executes at a single moment of time.

The import uses Coordinated Universal Time (UTC).

As an example of this, if a policy accessed time.now.second multiple times, for each access the same value would be returned even if they are several seconds apart. This is the execution timespace, which is mapped to time.now.

It is also possible to run functions on a custom time by using the time.load() function to create a new timespace from the specified value. See the documentation for available actions on timespaces.

Times specified as the reference time or via the time.load() function can be specified in a timeish fashion. This is either one of:

  • The number of seconds since the Unix epoch (Thursday, 1 January 1970, 00:00:00 UTC),
  • A timestamp matching the format outlined in RFC3339, either in the format 2006-01-02T15:04:05+07:00, which includes a timezone offset, or 2006-01-02T15:04:05Z, which indicates UTC.


Create a timespace locked either to execution time or, if set, the reference time. In a given execution, this will always produce the same value.

time.now // {"day": 17, "hour": 23, "minute": 19, "month": 11 ... }


Create a timespace using the given value. Please see the import documentation for valid values for "timeish".

time.load("2019-11-16T01:20:30Z") // {"day": 16, "hour": 1, "minute": 20, "month": 11 ... }


A nanosecond duration unit for use with the add timespace function.

time.load("2019-11-16T01:20:30Z").add(time.nanosecond * 1) // 2019-11-16T01:20:30.000000001Z


A microsecond duration unit for use with the add timespace function.

time.load("2019-11-16T01:20:30Z").add(time.microsecond * 1) // 2019-11-16T01:20:30.000001Z


A millisecond duration unit for use with the add timespace function.

time.load("2019-11-16T01:20:30Z").add(time.millisecond * 1) // 2019-11-16T01:20:30.001Z


A second duration unit for use with the add timespace function.

time.load("2019-11-16T01:20:30Z").add(time.second * 1) // 2019-11-16T01:20:31Z


A minute for use with the add timespace function.

time.load("2019-11-16T01:20:30Z").add(time.minute * 1) // 2019-11-16T01:21:30Z


An hour duration unit for use with the add timespace function.

time.load("2019-11-16T01:20:30Z").add(time.hour * 1) // 2019-11-16T02:20:30Z

»Type: timespace


The hour from 0 to 23.

time.load("2019-11-16T01:20:30Z").hour // 1


The minute from 0 to 59.

time.load("2019-11-16T01:20:30Z").minute // 20


The second from 0 to 59.

time.load("2019-11-16T01:20:30Z").second // 30


The day of the month, starting from 1.

time.load("2019-11-16T01:20:30Z").day // 16


The month of the year as an integer, starting from 1.

time.load("2019-11-16T01:20:30Z").month // 11


The name of the month of the year, in English. Example: January.

time.load("2019-11-16T01:20:30Z").month_name // November


The weekday as an integer, where 0 is Sunday and 6 is Saturday.

time.load("2019-11-16T01:20:30Z").weekday // 6


The name of the day of the week, in English. Example: Sunday.

time.load("2019-11-16T01:20:30Z").weekday_name // Saturday


The year as an integer.

time.load("2019-11-16T01:20:30Z").year // 2019


The number of seconds since the Unix epoch.

time.load("2019-11-16T01:20:30Z").unix // 1573867230


The number of nanoseconds since the Unix epoch.

time.load("2019-11-16T01:20:30Z").unix_nano // 1573867230000000000


The timezone offset, in seconds. This can be a negative number to indicate time west of UTC.

time.load("2019-11-16T01:20:30-08:00").zone // -28800


The timezone offset, in the format +HH:MM (example: -08:00 for PST).

time.load("2019-11-16T01:20:30-08:00").zone_string // -08:00


Check if the time in the timespace is before the given time

time.load("2019-11-16T01:20:30Z").before("2019-11-15T01:20:30Z") // false


Check if the time in the timespace is after the given time

time.load("2019-11-16T01:20:30Z").after("2019-11-15T01:20:30Z") // true


Check if two times are equivalent

time.load("2019-11-16T01:20:30Z").equal("2019-11-15T01:20:30Z") // false


Add a duration in nanoseconds to the time in the timespace and return a new timespace. The duration can be negative. The duration should be specified as an integer multiplied with the correct unit.

time.load("2019-11-16T01:20:30Z").add(time.hour * 1) // 2019-11-16T02:20:30Z


Subtract a time from the time in the timespace and return a duration in nanoseconds.

// Gives a duration of 3 hours.
duration = time.load(

// Returns 2019-11-16T01:20:30Z