Temporal functions¶
Temporal functions in NebulaGraph Database Developer Edition work with date, time, and duration values in persistent graphs and temporary graphs.
Temporal functions allow you to create and manipulate values of temporal types, such as DATE, ZONED TIME, LOCAL TIME, ZONED DATETIME, LOCAL DATETIME, and DURATION. For more information about the temporal types, see Temporal types.
GQL allows you to define temporal value formats in temporal functions. Additionally, you can use the default format to pass in the time value. To view the default format, see SHOW CURRENT_SESSION TIME FORMATS.
date()¶
Parses a string into a date.
Null behavior: default
Function signature¶
date(s: STRING) -> DATE
Examples¶
RETURN date('2022-01-02') AS `date`
Return:
+------------+
| date |
+------------+
| 2022-01-02 |
+------------+
local_datetime()¶
Parses a string into a local datetime.
Null behavior: default
Function signature¶
local_datetime(datetime: str, format: str) -> LOCAL DATETIME
Examples¶
Parse a local datetime with fractional seconds¶
RETURN local_datetime("2012-03-04T05:06:07.0890", "%Y-%m-%dT%H:%M:%S") AS localdatetime
The preceding example formats the local datetime using the format %Y-%m-%dT%H:%M:%S. The value 2012-03-04T05:06:07.0890 is parsed using the format to yield 2012-03-04T05:06:07.089000.
Return:
+----------------------------+
| localdatetime |
+----------------------------+
| 2012-03-04T05:06:07.089000 |
+----------------------------+
Parse a local datetime without fractional seconds¶
RETURN local_datetime("2012-03-04T05:06:07", "%Y-%m-%dT%H:%M:%S") AS localdatetime
The preceding example formats the local datetime without fractional seconds using the format %Y-%m-%dT%H:%M:%S, which means the fractional seconds are assumed to be 000000. The value 2012-03-04T05:06:07 is parsed using the format to yield 2012-03-04T05:06:07.000000.
Return:
+----------------------------+
| localdatetime |
+----------------------------+
| 2012-03-04T05:06:07.000000 |
+----------------------------+
Insert and query a local datetime¶
The following example is based on the example dataset. It inserts a local datetime into the graph and queries the inserted local datetime.
Insert a local datetime:
// Define a graph type with a local datetime property
ALTER GRAPH TYPE movie_type {ADD NODE `local_datetime` ({id INT PRIMARY KEY, event LOCAL DATETIME})}
// Insert a local datetime
USE movie INSERT (@`local_datetime`{id:1, event:local_datetime("2012-03-04T05:06:07", "%Y-%m-%dT%H:%M:%S")})
Query the inserted local datetime:
USE movie MATCH (a@`local_datetime`{id:1}) RETURN a
Return:
+-----------------------------------------------------------------------------+
| a |
+-----------------------------------------------------------------------------+
| (289670744974032900@local_datetime:{event:2012-03-04T05:06:07.000000,id:1}) |
+-----------------------------------------------------------------------------+
zoned_datetime()¶
Parses a string into a zoned datetime and returns the datetime in the time zone of the current session.
Null behavior: default
Function signature¶
zoned_datetime(datetime: str, format: str) -> ZONED DATETIME
Examples¶
Parse a zoned datetime with a specified time zone¶
RETURN zoned_datetime("2012-03-04ZONE05:06:07.123 AT -02:00", "%Y-%m-%dZONE%H:%M:%S AT %Ez") AS zoneddatetime
The preceding example uses the format %Y-%m-%d at %H:%M:%S ZONE %Ez to specify the zoned datetime. The value 2012-03-04 at 05:06:07 ZONE -02:00, which means the local time is 2 hours behind UTC, is parsed using this format to yield the session time 2012-03-04T07:06:07.123000Z.
Return:
+-----------------------------+
| zoneddatetime |
+-----------------------------+
| 2012-03-04T07:06:07.123000Z |
+-----------------------------+
Parse a zoned datetime with the default time zone¶
RETURN zoned_datetime("2012-03-04T05:06:07.0890", "%Y-%m-%dT%H:%M:%S") AS zoneddatetime
The preceding example formats the zoned datetime using the format %Y-%m-%dT%H:%M:%S with the default time zone +00:00. The value 2012-03-04T05:06:07.0890 is parsed using the format to yield the session time 2012-03-04T05:06:07.089000Z.
Return:
+-----------------------------+
| zoneddatetime |
+-----------------------------+
| 2012-03-04T05:06:07.089000Z |
+-----------------------------+
zoned_time()¶
Parses a string into a zoned datetime and returns the datetime in the time zone of the current session.
Null behavior: default
Function signature¶
zoned_time(time: str, format: str) -> ZONED TIME
Examples¶
Parse a zoned time with a specified time zone¶
RETURN zoned_time("05:06:07.123 AT -02:00", "%H:%M:%S AT %Ez") AS zonedtime
Return:
+------------------+
| zonedtime |
+------------------+
| 07:06:07.123000Z |
+------------------+
local_time()¶
Parses a string into a local time.
Null behavior: default
Function signature¶
local_time(time: str, format: str) -> LOCAL TIME
Examples¶
Parse a local time with fractional seconds¶
RETURN local_time("05:06:07.123", "%H:%M:%S") AS localtime
Return:
+-----------------+
| localtime |
+-----------------+
| 05:06:07.123000 |
+-----------------+
CURRENT_TIME / CURRENT_TIMESTAMP¶
CURRENT_TIME and CURRENT_TIMESTAMP are keyword-style zero-argument functions that return the current session time.
CURRENT_TIME: Returns the current zoned time in the current session time zone.CURRENT_TIMESTAMP: Returns the current zoned datetime in the current session time zone.
Null behavior: not applicable (no input arguments).
Examples¶
Query the current session time:
RETURN CURRENT_TIME AS now_time, CURRENT_TIMESTAMP AS now_ts
Set the session time zone first, then query the current time:
SESSION SET timezone = "Asia/Shanghai"
RETURN CURRENT_TIME AS sh_time, CURRENT_TIMESTAMP AS sh_ts
To check the current session time zone, see SHOW CURRENT_SESSION.
from_epoch()¶
Converts a Unix timestamp in microseconds to a zoned datetime.
Null behavior: default
Function signature¶
from_epoch(unix timestamp: INT64) -> ZONEDDATETIME
Examples¶
Convert a Unix timestamp to a zoned datetime¶
RETURN from_epoch(1333670400000*1000) AS dt
Return:
+-----------------------------+
| dt |
+-----------------------------+
| 2012-04-06T00:00:00.000000Z |
+-----------------------------+
Convert a Unix timestamp to a local datetime¶
LET zd = from_epoch(1333670400000*1000)
RETURN CAST(zd AS LOCAL DATETIME) AS ld
Return:
+----------------------------+
| ld |
+----------------------------+
| 2012-04-06T00:00:00.000000 |
+----------------------------+
to_epoch()¶
Converts a zoned datetime to a Unix timestamp in microseconds.
Null behavior: default
Function signature¶
to_epoch(time: ZONEDDATETIME) -> INT64
Examples¶
Convert a zoned datetime to a Unix timestamp¶
RETURN to_epoch(zoned_datetime("2012-04-06T08:00:00.000+08")) AS epoch
Return:
+------------------+
| epoch |
+------------------+
| 1333670400000000 |
+------------------+
Convert a local datetime to a Unix timestamp¶
LET zd = CAST(local_time("05:06:07.123", "%H:%M:%S") AS ZONED DATETIME)
RETURN to_epoch(zd) AS epoch
Return:
+------------------+
| epoch |
+------------------+
| 1749704767123000 |
+------------------+
duration()¶
Parses a map into a duration and returns the duration as a string which is formatted as P[nY][nM][nD]T[nH][nM][fS] following the ISO 8601 standard, where P is the duration designator and T is the time designator. The P designators are mandatory. The square brackets ([]) denote an optional component (components with a zero value may be omitted). n can be a positive integer, zero, or a negative integer. f can be a positive, zero, or negative integer or decimal. For more information, see Specifying a duration.
Function signature¶
duration({years: int = 0, months: int = 0, days: int = 0, hours: int = 0, minutes: int = 0, seconds: int = 0, milliseconds: int = 0, microseconds: int = 0}) -> str
Examples¶
Parse a duration with years and months¶
RETURN duration({years:1, months:2}) AS a
Return:
+-------+
| a |
+-------+
| P1Y2M |
+-------+
Parse a duration with days, hours, minutes, seconds, milliseconds, and microseconds¶
RETURN duration({days:1, hours:2, minutes:3, seconds:4, milliseconds:5, microseconds:6}) AS a
Return:
+-------------------+
| a |
+-------------------+
| P1DT2H3M4.005006S |
+-------------------+
Parse a duration with only years¶
RETURN duration({years:1}) AS a
Return:
+-----+
| a |
+-----+
| P1Y |
+-----+
Parse a duration with days and hours¶
RETURN duration({days:1, hours:2}) AS a
Return:
+--------+
| a |
+--------+
| P1DT2H |
+--------+
duration_between()¶
Calculates the duration between two temporal instant values and returns the duration as a string.
Function signature¶
duration_between(start: TEMPORAL_INSTANT, end: TEMPORAL_INSTANT) [ DAY TO SECOND | YEAR TO MONTH ] -> str
Parameters¶
start: The starting temporal instant value.end: The ending temporal instant value.DAY TO SECOND: Returns the duration in days, hours, minutes, and seconds. This is the default value.YEAR TO MONTH: Returns the duration in years and months.
Examples¶
Calculate the duration between two local datetimes¶
RETURN duration_between(local_datetime("2024-05-31T06:07:08.0900"), local_datetime("2024-5-1T01:02:03.0400")) AS a
Return:
+----------------+
| a |
+----------------+
| P30DT5H5M5.05S |
+----------------+
Calculate the duration between two dates¶
RETURN duration_between(date("2024-5-30"), date("2024-6-30")) YEAR TO MONTH AS a
Return:
+------+
| a |
+------+
| P-1M |
+------+
Operations between temporal instants and durations¶
For supported operations between temporal instants and durations, see Temporal Types.
Examples¶
Add a duration to a date¶
RETURN date("2024-05-30") + duration({years: 1000, months: 10}) AS a
Return:
+------------+
| a |
+------------+
| 3025-03-30 |
+------------+
Subtract a duration from a date¶
RETURN date("2022-04-30") - duration({years: 2, months: 2}) AS a
Return:
+------------+
| a |
+------------+
| 2020-02-29 |
+------------+
Add a duration to a local time¶
RETURN local_time("01:02:03.0400") + duration({hours: 3, minutes: 3, seconds: 3, microseconds: 30000}) AS a
Return:
+-----------------+
| a |
+-----------------+
| 04:05:06.070000 |
+-----------------+
Subtract a duration from a local datetime (less than one day)¶
RETURN local_datetime("2024-05-31T01:05:05.0500") - duration({hours: 3, minutes: 3, seconds: 3, microseconds: 30000}) AS a
Return:
+----------------------------+
| a |
+----------------------------+
| 2024-05-30T22:02:02.020000 |
+----------------------------+
Subtract a duration from a local datetime (more than one day)¶
RETURN local_datetime("2021-02-28T03:03:03.0000") - duration({days: 365}) AS a
Return:
+----------------------------+
| a |
+----------------------------+
| 2020-02-29T03:03:03.000000 |
+----------------------------+