Date and time types
Learn about 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.
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 2023-01-01 represents the first day of the year 2023, 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:
- dayinteger
The day of the month, from 1 to 31.
- weekdaystring
The name of the day of the week, such as "monday" or "tuesday".
The name is always in lowercase and in English.
- monthinteger
The month of the year, from 1 to 12.
- yearinteger
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.
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:
- hourinteger
The hour of the day, from 0 to 23.
- minuteinteger
The minute of the hour, from 0 to 59.
- secondinteger
The second of the minute, from 0 to 59.
- milliinteger
The millisecond of the second, from 0 to 999.
- microinteger
The microsecond of the second, from 0 to 999999.
- nanointeger
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.
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:
- dayinteger
The day of the month, from 1 to 31.
- weekdaystring
The name of the day of the week, such as "monday" or "tuesday".
The name is always in lowercase and in English.
- monthinteger
The month of the year, from 1 to 12.
- yearinteger
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.
- hourinteger
The hour of the day, from 0 to 23.
- minuteinteger
The minute of the hour, from 0 to 59.
- secondinteger
The second of the minute, from 0 to 59.
- milliinteger
The millisecond of the second, from 0 to 999.
- microinteger
The microsecond of the second, from 0 to 999999.
- nanointeger
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.