Date and time types¶

This topic will describe the DATE, TIME, DATETIME, and TIMESTAMP types.

While inserting time-type property values, except for TIMESTAMP, 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.

• date(), time(), datetime(), and timestamp() all accept empty parameters to return the current date, time, and datetime.

• date(), time(), and datetime() all accept the property name to return a specific property value of itself. For example, date().month returns the current month, while time("02:59:40").minute returns the minutes of the importing time.

OpenCypher Compatibility¶

In nGQL:

• Year, month, day, hour, minute, and second are supported, while the millisecond is not supported.

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

• Most string time formats are not supported. The exceptions are YYYY-MM-DDThh:mm:ss and YYYY-MM-DD hh:mm:ss.

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.

The properties of date() include year, month, and day.

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.msmsmsususus format. The supported range is 00:00:00.000000 to 23:59:59.999999.

The properties of time() include hour, minute, and second.

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-DDThh:mm:ss.msmsmsususus format. The supported range is -32768-01-01T00:00:00.000000 to 32767-12-31T23:59:59.999999.

The properties of datetime() include year, month, day, hour, minute, and second.

TIMESTAMP¶

The TIMESTAMP data type is used for values that contain both date and time parts. It has a range of 1970-01-01T00:00:01 UTC to 2262-04-11T23:47:16 UTC.

TIMESTAMP has the following features:

• Stored and displayed in the form of a timestamp, such as 1615974839, which means 2021-03-17T17:53:59.

• Supported TIMESTAMP querying methods: timestamp and timestamp() function.

• Supported TIMESTAMP inserting methods: timestamp, timestamp() function, and now() function.

• timestamp() function accepts empty parameters to get the timestamp of the current time zone and also accepts a string type parameter.

  # Return the current time.
  nebula> RETURN timestamp();
  +-------------+
  | timestamp() |
  +-------------+
  | 1625469277  |
  +-------------+
  
  # Return the specified time.
  nebula> RETURN timestamp("2021-07-05T06:18:43.984000");
  +-----------------------------------------+
  | timestamp("2021-07-05T06:18:43.984000") |
  +-----------------------------------------+
  | 1625465923                              |
  +-----------------------------------------+
  

• The underlying storage data type is int64.

Examples¶

1. Create a tag named date1 with three properties: DATE, TIME, and DATETIME.

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

2. Insert a vertex named test1.

   nebula> INSERT VERTEX date1(p1, p2, p3) VALUES "test1":(date("2021-03-17"), time("17:53:59"), datetime("2021-03-17T17:53:59"));
   

3. Return the content of the property p1 on test1.

   nebula> CREATE TAG INDEX date1_index ON date1(p1);
   nebula> REBUILD TAG INDEX date1_index;
   nebula> MATCH (v:date1) RETURN v.p1;
   +------------+
   | v.p1       |
   +------------+
   | 2021-03-17 |
   +------------+
   

4. Create a tag named school with the property of TIMESTAMP.

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

5. Insert a vertex named DUT with a found-time timestamp of "1988-03-01T08:00:00".

   # Insert as a timestamp. The corresponding timestamp of 1988-03-01T08:00:00 is 573177600, or 573206400 UTC.
   nebula> INSERT VERTEX school(name, found_time) VALUES "DUT":("DUT", 573206400);
   
   # Insert in the form of date and time.
   nebula> INSERT VERTEX school(name, found_time) VALUES "DUT":("DUT", timestamp("1988-03-01T08:00:00"));
   

6. Insert a vertex named dut and store time with now() or timestamp() functions.

   # Use now() function to store time
   nebula> INSERT VERTEX school(name, found_time) VALUES "dut":("dut", now());
   
   # Use timestamp() function to store time
   nebula> INSERT VERTEX school(name, found_time) VALUES "dut":("dut", timestamp());
   

You can also use WITH statement to set a specific date and time. For example:

nebula> WITH time({hour: 12, minute: 31, second: 14, millisecond:111, microsecond: 222}) AS d RETURN d;
+-----------------+
| d               |
+-----------------+
| 12:31:14.111222 |
+-----------------+

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