Source: https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/fe/functions/temporal/
Documentation version: v5.3.2

# 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/temporal-type/).

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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/overview/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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-admin/show/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](https://www.iso.org/iso-8601-date-and-time-format.html), 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/temporal-type/#specify_durations).

### 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](https://dev-docs.nebula-graph.io/v5.3.2/database-gql-reference/data-types/temporal-type/).

### 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 |
+----------------------------+

````