Datetime Functions

Datetime Value Functions

A datetime value function creates a temporal instant or duration value. Refer to Values and Types for date and time string formats.

date()

Creates a value of type DATE (LOCAL DATE).

GQL
// returns the current local date, date() is equivalent to CURRENT_DATE
RETURN date(), CURRENT_DATE

GQL
RETURN date("1993-05-09"),
       date("1993-5-9"),
       date("19930509"),
       date("1993/05/09"),
       date("1993/5/9"),
       date({year: 1993, month: 5, day: 9}),
       date(1993, 5, 9)

local_time()

Creates a value of type LOCAL TIME. time() is a synonym.

GQL
// returns the current local time, local_time() is equivalent to LOCAL_TIME
RETURN local_time(), LOCAL_TIME

GQL
RETURN local_time("03:02:11.700000000"),
       local_time("03:02:11"),
       local_time("03:02"),
       local_time("030211"),
       local_time("030211.700000000"),
       local_time({hour: 3, minute: 2, second: 11}),
       local_time({hour: 3, minute: 2, second: 11, millisecond: 700}),
       local_time({hour: 3, minute: 2, second: 11, microsecond: 700}),
       local_time({hour: 3, minute: 2, second: 11, nanosecond: 700})

local_datetime()

Creates a value of type LOCAL DATETIME.

GQL
// returns the current local datetime, local_datetime() is equivalent to LOCAL_TIMESTAMP
RETURN local_datetime(), LOCAL_TIMESTAMP

GQL
RETURN local_datetime("1993-05-09T03:02:11.70"),
       local_datetime("1993-05-09 03:02:11"),
       local_datetime("1993/05/09 03:02:11"),
       local_datetime("1993/5/9 03:02:11"),
       local_datetime("19930509T030211"),
       local_datetime("19930509 030211"),
       local_datetime({year: 1993, month: 5, day: 9, hour: 3, minute: 2, second: 11}),
       local_datetime({year: 1993, month: 5, day: 9, hour: 3, minute: 2, second: 11, millisecond: 700}),
       local_datetime({year: 1993, month: 5, day: 9, hour: 3, minute: 2, second: 11, microsecond: 700}),
       local_datetime({year: 1993, month: 5, day: 9, hour: 3, minute: 2, second: 11, nanosecond: 700})

zoned_time()

Creates a value of type ZONED TIME.

GQL
// returns the current local zoned time, zoned_time() is equivalent to CURRENT_TIME
RETURN zoned_time(), CURRENT_TIME

GQL
RETURN zoned_time("12:20:02+08:00"),
       zoned_time("12:20:02Z"),
       zoned_time({hour: 12, minute: 20, second: 2, timezone: "+08:00"}),
       zoned_time({hour: 12, minute: 20, second: 2, timezone: "+08:00", millisecond: 500}),
       zoned_time({hour: 12, minute: 20, second: 2, timezone: "-06:00", microsecond: 700}),
       zoned_time({hour: 12, minute: 20, second: 2, timezone: "Z", nanosecond: 700})

Convert an existing time to a different timezone:

GQL
RETURN zoned_time("12:20:02+08:00", "+05:30")

zoned_datetime()

Creates a value of type ZONED DATETIME.

GQL
// returns the current local datetime, zoned_datetime() is equivalent to CURRENT_TIMESTAMP
RETURN zoned_datetime(), CURRENT_TIMESTAMP

GQL
RETURN zoned_datetime("2025-01-01T12:20:02+08:00"),
       zoned_datetime("2025-01-01T12:20:02Z"),
       zoned_datetime({year: 2025, month: 1, day: 1, hour: 12, minute: 20, second: 2, timezone: "+08:00"}),
       zoned_datetime({year: 2025, month: 1, day: 1, hour: 12, minute: 20, second: 2, timezone: "+08:00", millisecond: 500}),
       zoned_datetime({year: 2025, month: 1, day: 1, hour: 12, minute: 20, second: 2, timezone: "-06:00", microsecond: 700}),
       zoned_datetime({year: 2025, month: 1, day: 1, hour: 12, minute: 20, second: 2, timezone: "Z", nanosecond: 700})

Convert an existing datetime to a different timezone:

GQL
RETURN zoned_datetime("2025-01-01T12:20:02+08:00", "+05:30")

now()

Returns the current zoned datetime in the server's local timezone. It is equivalent to CURRENT_TIMESTAMP.

GQL
RETURN now(), CURRENT_TIMESTAMP

duration()

Creates a value of type DURATION.

GQL
RETURN duration("P2Y5M"), duration("P3DT4H30M")

Other Datetime Functions

date_add()

Adds a specified time interval to a given date.

GQL
RETURN date_add("1970-1-1", -1, "hour")

Result:

JSON
{
  "_type": "localDatetime",
  "year": 1969,
  "month": 12,
  "day": 31,
  "hour": 23,
  "minute": 0,
  "second": 0,
  "nanosecond": 0
}

GQL
RETURN date_add("1970-1-1", 10, "year")

Result:

JSON
{
  "_type": "localDatetime",
  "year": 1980,
  "month": 1,
  "day": 1,
  "hour": 0,
  "minute": 0,
  "second": 0,
  "nanosecond": 0
}

date_diff()

Computes the difference between two dates (time1 - time2) and returns the result as a specified unit of time.

GQL
RETURN date_diff("1970-01-01 10:00:00", "1970-01-01 12:00:20", "minute")

Result: -120

day_of_week()

Returns a number (from 0 to 6, where 0 = Sunday and 6 = Saturday) representing the day of the week for a given date.

GQL
RETURN day_of_week("2024-12-5")

Result: 4

year()

Extracts the year from a date or datetime value.

GQL
RETURN year("2025-03-15"), year(date("2025-03-15"))

month()

Extracts the month from a date or datetime value.

GQL
RETURN month("2025-03-15"), month(date("2025-03-15"))

day()

Extracts the day from a date or datetime value.

GQL
RETURN day("2025-03-15"), day(date("2025-03-15"))

hour()

Extracts the hour from a time or datetime value.

GQL
RETURN hour("2025-03-15 14:30:45"), hour(local_datetime("2025-03-15 14:30:45"))

minute()

Extracts the minute from a time or datetime value.

GQL
RETURN minute("2025-03-15 14:30:45"), minute(local_datetime("2025-03-15 14:30:45"))

second()

Extracts the second from a time or datetime value.

GQL
RETURN second("2025-03-15 14:30:45"), second(local_datetime("2025-03-15 14:30:45"))

duration_between()

Computes the duration between two temporal values.

GQL
RETURN duration_between(date("2025-01-01"), date("2025-03-15"))

Result:

JSON
{
  "seconds": 6307200, "nanoseconds": 0
}

dateformat()

Formats a temporal value as a string using a Java SimpleDateFormat-style pattern.

Supported pattern tokens (case-sensitive; the longest match wins):

GQL
RETURN dateformat(date("2025-03-15"), "yyyy-M-d") AS value1,
       dateformat(local_datetime("2025-03-15T14:30:45"), "yyyy-MM-dd HH:mm:ss") AS value2
       dateformat(CURRENT_DATE, "'today is' yyyy-MM-dd") AS value3  // single-quote escape

Result: