Temporal types

Temporal values are used for the storage, manipulation, and retrieval of date and time information. GQL comes with built-in support for temporal values that can be stored as property values on nodes and edges. The following sections explain the temporal types and how to use them.

Categories of temporal values

Temporal values fall into two categories: temporal instant values and temporal duration values.

• Temporal instant value: Represents a specific point in time, such as a date or a time.
• Temporal duration value: Represents a time difference between two temporal instant values.

Temporal instants

Temporal instants can be specified using the following elements: date, time, and time zone. These elements can be combined in various ways to create a temporal instant. Temporal instant types include zoned datetime, local datetime, date, zoned time, and local time.

• A zoned datetime includes a time, a date, and a time zone. It's the most specific as it indicates the exact moment in time worldwide.
• A local datetime includes a time and a date but doesn't include a time zone. It specifies a moment in time but only for a local region, not globally.
• A date signifies a calendar date (year, month, day) that remains unaffected by time zone considerations.
• A zoned time includes a time and a time zone. It represents the same clock time, observed on different days, in a specific time zone.
• A local time includes only a time. It's the least specific, representing a time of day without any date or time zone context.

The following table lists the temporal instant types, their declaration keywords, and value ranges.

Type	Declaration keywords	Date support	Time support	Time zone support	Range
Zoned datetime	ZONED DATETIME	Yes	Yes	Yes	-9999-01-01T00:00:00.000000+1400 ~ 9999-12-31T23:59:59.999999-1200
Local datetime	LOCAL DATETIME	Yes	Yes	No	-9999-01-01T00:00:00.000000 ~ 9999-12-31T23:59:59.999999
Date	DATE	Yes	No	No	-9999-01-01 ~ 9999-12-31
Zoned time	ZONED TIME	No	Yes	Yes	00:00:00.000000+1400 ~ 23:59:59.99999-1200
Local time	LOCAL TIME	No	Yes	No	00:00:00.000000 ~ 23:59:59.999999

• The declaration keywords are used to specify the temporal instant type when you create a property.

• The range format is an example. You can specify a temporal instant value in the format defined by you. For more information, see Temporal instant value formats.

Temporal durations

A temporal duration can be specified using the following elements: years, months, days, hours, minutes, seconds, milliseconds, and microseconds. These elements can be combined in various ways to create a temporal duration. The keyword DURATION is used to declare a duration. A temporal duration value can be positive, zero, or negative. For how to specify a duration, see Specify durations.

Temporal value formats

You have the flexibility to define the format in which you want to represent these values. However, the chosen format must adhere to the guidelines provided by the ISO 8601 standard. Once you specify the desired format, you should provide the temporal value in that format.

In the following example, %Y-%m-%dT%H:%M:%S is the temporal value format defined by you, and 2012-03-04T05:06:07.0890 is the value specified in the format.

local_datetime("2012-03-04T05:06:07.0890", "%Y-%m-%dT%H:%M:%S") AS localdatetime

Note

• In GQL, you insert a property value of the temporal types by using a temporal function.
• If you specify a temporal value in the default format, you can omit the value format. For example, you can directly use local_datetime("2012-03-04T05:06:07.0890") without specifying the format in the above example.

A temporal value format is a string that consists of the following elements:

Element	Description	Range
%Y	A year	-9999 ~ 9999
%y	A two-digit year	00 ~ 99
%m	A two-digit month of the year	01 ~ 12
%d	A two-digit day of the month	01 ~ 31
%H	A hour of the day, 24-hour clock	00 ~ 23
%I	A hour of the day, 12-hour clock	01 ~ 12
%M	A two-digit minute of the hour	00 ~ 59
%S	A two-digit second of the minute. It includes fractional seconds, with up to six digits after the decimal point. When no fractional seconds are specified, zeros are padded to the right of the decimal point.	00 ~ 59.999999
%f	Fractional seconds	000000 ~ 999999
%a	An abbreviated weekday name	Mon, Tue, Wed, Thu, Fri, Sat, Sun
%A	A full weekday name	Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
%b	An abbreviated month name	Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec
%B	A full month name	January, February, March, April, May, June, July, August, September, October, November, December
%z	Timezone offset relative to UTC. For example, -0430 refers to 4 hours and 30 minutes behind UTC. If the offset is zero, +0000 is used.	-1200 ~ +1400
%Ez	Similar to %z, the difference is that a colon is needed between the hours and minutes, for example, -04:30. If the offset is zero, +00:00 is used.	-12:00 ~ +14:00

Specify times

The %H/%I, %M, %S, and %z/%Ez elements are used to format the time. For example, 05:06:07.089 is a time specified in the format %H:%M:%S. The element %H/%I must be specified in the format.

A time is either a zoned time with the default format %H:%M:%S %z, or a local time with the default format %H:%M:%S. If the time zone is specified, the time is a zoned time; otherwise, it is a local time. For example:

• A local time:

  local_time("05:06:07.089", "%H:%M:%S") AS localtime
  

• A zoned time:

  zoned_time("05:06:07.089 +08:00", "%H:%M:%S %Ez") AS zonetime
  

It is not required to specify the trailing zeros for fractional seconds. For example, 05:06:07.089000 can be specified as 05:06:07.089. Note that if the number of fractional seconds is less than the maximum number of fractional seconds, zeros are padded to the end of the number to reach the required length.

If the time elements are not specified, the time defaults to 00:00:00.000000.

Specify time zones

A time zone is a region of the globe that observes a uniform standard time for legal, commercial, and social purposes. It is represented by the time zone displacement, which is the difference between the local time and Universal Coordinated Time (UTC).

The %z or %Ez element is used to format the time zone displacement. When the time zone displacement is used with the local time, results are converted to UTC. For information about the time zone identifiers and their corresponding displacements, see List of tz database time zones.

When specifying a time zone displacement from UTC, the following guidelines apply:

• The displacement is parsed as a four-digit number, such as HHMM, where HH is the hours and MM is the minutes. An optional colon (:) can be used to separate the hours and minutes, for example, +08:00.
  • When using %z to format the time zone, the value must be a four-digit number.
  • When using %Ez to format the time zone, the value must be a four-digit number with a mandatory colon separating the hours and minutes.
• The displacement is positive if the local time is ahead of UTC, indicated by a + sign or no sign.
• The displacement is negative if the local time is behind UTC, indicated by a - sign.
• When the time zone element and the corresponding value are not specified in a zoned time or zoned datetime, the time zone defaults to +00:00 when the displacement is zero.

The following exemplifies the use of the %z element to specify a time zone displacement. 2016-09-20T01:01:01.123456 is the local time and +0800 is the displacement. The returned value 2016-09-20T01:01:01.123456+08:00 is Universal Coordinated Time.

zoned_datetime("2016-09-20T01:01:01.123456 +0800", "%Y-%m-%dT%H:%M:%S %z") AS zoneddatetime 

Specify dates

The %Y/%y, %m/%b/%B, %d, and %a/%A elements are used to format the date. For example, Tue, 2016-09-20 is a date specified in the format %a, %Y-%m-%d. The %Y/%y, %m/%b/%B, and %d must be specified in the format.

The default format for a date is %Y-%m-%d. If the date and the matched day of the week are specified, the day of the week is ignored in the result. For example:

date("Tue, 2016-09-20", "%a, %Y-%m-%d") AS d

Return:

+------------+
| d          |
+------------+
| 2016-09-20 |
+------------+

In the above example, Tue, 2016-09-20T01:01:01 is equivalent to 2016-09-20T01:01:01. If the date and the day of the week do not match, a parsing error is returned.

Specify datetimes

A datetime is a combination of a date and a time. You can specify a datetime by using the date and time elements. A delimiter, such as T, must be used to separate the date and time elements. For example, 2016-09-20T01:01:01 is a datetime specified in the format %Y-%m-%dT%H:%M:%S. The elements %Y/%y, %m/%b/%B, and %d must be specified in the format.

A datetime can be either a zoned datetime with the default format %Y-%m-%dT%H:%M:%S %z, or a local datetime with the default format %Y-%m-%dT%H:%M:%S. If the time zone is specified, the datetime is a zoned datetime; otherwise, it is a local datetime. For example:

• A datetime without a time zone:

  local_datetime("2016-09-20T01:01:01.123456", "%Y-%m-%dT%H:%M:%S") AS localdatetime
  

  Return:

  +----------------------------+
  | localdatetime              |
  +----------------------------+
  | 2016-09-20T01:01:01.123456 |
  +----------------------------+
  

• A datetime with a time zone:

  zoned_datetime("2016-09-20T01:01:01.123456 +08:00", "%Y-%m-%dT%H:%M:%S %Ez") AS zoneddatetime
  

  Return:

  +-----------------------------+
  | zoneddatetime               |
  +-----------------------------+
  | 2016-09-19T17:01:01.123456Z |
  +-----------------------------+
  

Specify durations

Every temporal duration only uses the temporal duration units from exactly one of the following temporal duration unit groups:

• Year and month-based duration unit group: years and months, for example, duration({years:100, months:1}).
• Day and time-based duration unit group: days, hours, minutes, seconds, milliseconds, and microseconds, for example, duration({days:1, hours:2, minutes:3, seconds:4, milliseconds:4, microseconds:5}).

For each unit group, the unit values are specified as a map. The unit values are positive integers, zero, or negative integers. The unit values can be combined in various ways to create a temporal duration. The unit in the map is optional. If the unit is not specified, the value defaults to zero. For how to specify a duration, see duration().

Operators or functions for temporal type values

The following table lists the operators or functions that can be used with temporal type values. For more information, see Operations between temporal instants and durations.

Operand 1	Function/Operator	Operand 2	Result
temporal instant	duration_between()	temporal instant	temporal duration
temporal instant	+ or -	temporal duration	temporal instant
temporal duration	+	temporal instant	temporal instant
temporal duration	+ or -	temporal duration	temporal duration
temporal duration	* or /	number	temporal duration
number	*	temporal duration	temporal duration

Components of temporal instants

You can use the period (.) operator to access the components of temporal instants. The following table lists the supported components and provides examples on how to access them.

Component	Description	Temporal function example	Temporal literal example
year	The year of the temporal instant	RETURN zoned_datetime("2016-09-20T01:01:01 +08:00", "%Y-%m-%dT%H:%M:%S %Ez").year AS year	RETURN DATETIME "2016-09-20T01:01:01+0800".year AS year
month	The month of the temporal instant	RETURN date("Tue, 2016-09-20", "%a, %Y-%m-%d").month AS month	RETURN DATE "2016-09-20".month AS month
day	The day of the temporal instant	RETURN local_datetime("2016-09-20T01:01:01", "%Y-%m-%dT%H:%M:%S").day AS day	RETURN DATETIME "2016-09-20T01:01:01".day AS day
hour	The hour of the temporal instant	RETURN zoned_time("05:06:07.089 +08:00", "%H:%M:%S %Ez").hour AS hour	RETURN TIME "05:06:07.089+0800".hour AS hour
minute	The minute of the temporal instant	RETURN zoned_time("05:06:07.089 +08:00", "%H:%M:%S %Ez").minute AS minute	RETURN TIME "05:06:07.089+0800".minute AS minute
second	The second of the temporal instant	RETURN local_time("05:06:07.089", "%H:%M:%S").second AS second	RETURN TIME "05:06:07.089".second AS second

When you access a component that is not included in the temporal instant, the following rules apply:

• When accessing year, month, or day of a zoned time (ZONED TIME) or a local time (LOCAL TIME), the corresponding value of the current date is returned.
• When accessing hour, minute, or second of a date (DATE), the value 0 is returned for all three components.

More information

• Temporal functions
• Temporal literals