There are three types to represent three aspects of time and various ways to combine with with operators.

Types

• Date: A calendar day such as October 29, 1929.
• Timestamp: A date and time in UTC with second-level precision such as midnight UTC on January 1, 2000.
• Duration: An interval of time such as 23 hours, 56 minutes, and 4 seconds.

Date

A Date represents a calendar day. An example is October 29, 1929. A Date can be created with the date function.

The range of a Date is -999999999-01-01 to 999999999-12-31.

Operators

A Date can appear as the first operand in the following operations.

• Date - Date = Duration
• Date - Duration = Date
• Date + Duration = Date

These operations will raise an error if the result exceeds the supported range of the return type.

Timestamp

A Timestamp represents a date and time in UTC with precision to the second. An example is midnight UTC on January 1, 2000. A Timestamp can be created with the timestamp function.

The range of a Timestamp is -1000000000-01-01T00:00:00Z to 1000000000-12-31T23:59:59Z.

Operators

A Timestamp can appear as the first operand in the following operations.

• Timestamp - Timestamp = Duration
• Timestamp - Duration = Timestamp
• Timestamp + Duration = Timestamp

These operations will raise an error if the result exceeds the supported range of the return type.

Duration

A Duration is an interval of time. An example is 23 hours, 56 minutes, and 4 seconds. A Duration can be created with the duration function as well as the days, hours, minutes, and seconds functions.

The uptime of a device is an example of a Duration. See the uptime field of System.

The range of Duration is -9223372036854775807 to 9223372036854775807 seconds, which is over 291,672,107,014 years.

Operators

New Durations can be created from existing ones with these operators.

• -x: Negation
• x + y: Addition
• x - y: Subtraction

Addition and subtraction will raise an error the resulting interval of time exceeds the range supported by Duration.