Date and time types¶

This document describes the DATE, TIME, DATETIME, and TIMESTAMP types. Nebula Graph converts the DATE, TIME, DATETIME, and TIMESTAMP values from the current time zone to UTC for storage. Nebula Graph converts back from UTC to the current time zone for retrieval.

While inserting time-type property values, except for timestamps, Nebula Graph transforms them to a UTC time according to the time zone specified with the timezone_name parameter in the configuration files. The time-type values returned by nGQL queries are all UTC time.

Combined with RETURN, functions date(), time(), datetime() all accept empty parameters to return the current date, time and datetime.

OpenCypher Compatibility¶

In nGQL:

• Year, month, day, hour, minute, and second are supported. The millisecond field is displayed in 000.

• localdatetime(), duration() are not supported.

• Most string time formats are not supported. The only exception is 2017-03-04T22:30:40.

DATE¶

The DATE type is used for values with a date part but no time part. Nebula Graph retrieves and displays DATE values in the YYYY-MM-DD format. The supported range is -32768-01-01 to 32767-12-31.

TIME¶

The TIME type is used for values with a time part but no date part. Nebula Graph retrieves and displays TIME values in hh:mm:ss:usus format. The supported range is 0:0:0:0 to 23:59:59:999999.

DATETIME¶

The DATETIME type is used for values that contain both date and time parts. Nebula Graph retrieves and displays DATETIME values in YYYY-MM-DD hh:mm:ss:ususus format. The supported range is -32768-01-01 00:00:00:00 to 32767-12-31 23:59:59:999999.

TIMESTAMP¶

The TIMESTAMP data type is used for values that contain both date and time parts.

• TIMESTAMP has a range of 1970-01-01 00:00:01 UTC to 2262-04-11 23:47:16 UTC.
• Timestamp is measured in units of seconds.
• Supported TIMESTAMP inserting methods:
  • Call the now() function.
  • Input TIMESTAMP by using a string. For example: 2019-10-01 10:00:00.
  • Input TIMESTAMP directly, namely the number of seconds from 1970-01-01 00:00:00.
• The underlying storage data type is: int64.

Examples¶

Create a tag named date.

nebula> CREATE TAG date(p1 date, p2 time, p3 datetime);

Insert a vertex named Date1.

nebula> INSERT VERTEX date(p1, p2, p3) VALUES "Date1":(date("2017-03-04"), time("23:01:00"), datetime("2017-03-04T22:30:40"));

Create a tag named school.

nebula> CREATE TAG school(name string , found_time timestamp);

Insert a vertex named "stanford" with the foundation date "1885-10-01T08:00:00".

nebula> INSERT VERTEX school(name, found_time) VALUES "Stanford":("Stanford", timestamp("1885-10-01T08:00:00"));

Insert a vertex named "dut" with the foundation date now.

nebula> INSERT VERTEX school(name, found_time) VALUES "dut":("dut", now());

nebula> WITH time({hour: 12, minute: 31, second: 14}) AS d RETURN d;
+--------------+
| d            |
+--------------+
| 12:31:14.000 |
+--------------+

nebula> WITH date({year: 1984, month: 10, day: 11}) AS x RETURN x + 1;
+------------+
| x          |
+------------+
| 1984-10-12 |
+------------+

nebula> WITH datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14}) AS d \
        RETURN toString(d) AS ts, datetime(toString(d)) == d AS b
+-------------------------+------+
| ts                      | b    |
+-------------------------+------+
| "1984-10-11T12:31:14.0" | true |
+-------------------------+------+