Date and time types

Discover the date and time types available in CQL.

Date and time types refer to data types representing temporal values, such as dates, times, and durations. Each of these types represents a different concept with distinct properties and use cases.

This summary provides an overview of the date and time types:

Type	Description
Date	A date without time information.
Time	A time of day without date or time zone information.
Date-time	A date and with time information.
Duration	A period of time in a particular unit.

Date

This type represents a local date as defined by the ISO 8601 standard.

Defining date values

Although dates have no literal syntax, you can use the cast modifier to convert a string into a date value.

Local dates are what most people think of when they talk about dates. They do not represent a specific point in time, but rather a day in the calendar. For example, the date 2024-01-01 represents the first day of the year 2024, regardless of the time of day or daylight savings time adjustments.

Range

The range of valid dates is from -999999999-01-01 to 999999999-12-31.

Properties

These are the available properties:

day integer: The day of the month, from 1 to 31.
weekday string: The name of the day of the week, such as "monday" or "tuesday".
The name is always in lowercase and in English.
month integer: The month of the year, from 1 to 12.
year integer: The year, from -999999999 to 999999999.
This value follows the ISO 8601 standard and uses the proleptic numbering system. Therefore, year 1 is preceded by year 0, then by year -1.

Time

This type represents a time of day as defined by the ISO 8601 standard.

Defining time values

Although times have no literal syntax, you can use the cast modifier to convert a string into a date-time value.

Local times correspond to the time displayed on a 24-hour clock. They do not represent a specific point on the timeline but rather a time of day. For example, the time 12:00:00 represents noon, regardless of the date or time zone.

Range

The range of valid times is from 00:00:00 to 23:59:59.999999999.

Properties

These are the available properties:

hour integer: The hour of the day, from 0 to 23.
minute integer: The minute of the hour, from 0 to 59.
second integer: The second of the minute, from 0 to 59.
milli integer: The millisecond of the second, from 0 to 999.
micro integer: The microsecond of the second, from 0 to 999999.
nano integer: The nanosecond of the second, from 0 to 999999999.

Date-time

This type represents a specific date and time as defined by the ISO 8601 standard.

Defining date-time values

Although date-time values have no literal syntax, you can use the cast modifier to convert a string into a date-time value.

Date-time values refer to a specific point on the timeline, even if they are not associated with a time zone. With CQL, you do not have to worry about time zones because conversions consider the default time zone configured in your application, making the process seamless.

Range

The range of valid date times is from -999999999-01-01T00:00:00 to 999999999-12-31T23:59:59.999999999.

Properties

These are the available properties:

day integer: The day of the month, from 1 to 31.
weekday string: The name of the day of the week, such as "monday" or "tuesday".
The name is always in lowercase and in English.
month integer: The month of the year, from 1 to 12.
year integer: The year, from -999999999 to 999999999.
This value follows the ISO 8601 standard and uses the proleptic numbering system. Therefore, year 1 is preceded by year 0, then by year -1.
hour integer: The hour of the day, from 0 to 23.
minute integer: The minute of the hour, from 0 to 59.
second integer: The second of the minute, from 0 to 59.
milli integer: The millisecond of the second, from 0 to 999.
micro integer: The microsecond of the second, from 0 to 999999.
nano integer: The nanosecond of the second, from 0 to 999999999.

Duration

This type represents a period in a particular unit, such as months, days, or seconds.

A duration can be positive or negative, indicating a past or future period, respectively. Like all other time types, durations follow the ISO 8601 standard. This is why they are formatted as periods when converted to a string.

For more information, refer to the Duration reference.