10.2. Date and Time Conversions

This section describes functions for working with dates and times.

10.2.1. Conversion between formatted dates and timestamps

apoc.date.parse('2015/03/25 03:15:59',['ms'/'s'], ['yyyy/MM/dd HH:mm:ss'])

same as previous, but accepts custom datetime format

apoc.date.format(12345, ['ms'/'s'], ['yyyy/MM/dd HH:mm:ss'])

the same as previous, but accepts custom datetime format

apoc.date.systemTimezone()

return the system timezone display format string

apoc.date.currentTimestamp()

provides current time millis with changing values over a transaction

  • possible unit values: ms,s,m,h,d and their long forms millis,milliseconds,seconds,minutes,hours,days.
  • possible time zone values: Either an abbreviation such as PST, a full name such as America/Los_Angeles, or a custom ID such as GMT-8:00. Full names are recommended. You can view a list of full names in this Wikipedia page.

10.2.2. Current timestamp

apoc.date.currentTimestamp() provides the System.currentTimeMillis which is current throughout transaction execution compared to Cypher’s timestamp() function which does not update within a transaction

The following captures the current timestamp, sleeps for 1 second, and then captures the current timestamp again: 

WITH apoc.date.currentTimestamp() as start
CALL apoc.util.sleep(1000)
RETURN start, apoc.date.currentTimestamp() AS end;

Table 10.8. Results
Start End

1561386222609

1561386223612

10.2.3. Conversion of timestamps between different time units

  • apoc.date.convert(12345, 'ms', 'd') convert a timestamp in one time unit into one of a different time unit
  • possible unit values: ms,s,m,h,d and their long forms.

10.2.4. Adding/subtracting time unit values to timestamps

  • apoc.date.add(12345, 'ms', -365, 'd') given a timestamp in one time unit, adds a value of the specified time unit
  • possible unit values: ms,s,m,h,d and their long forms.

10.2.5. Reading separate datetime fields:

Splits date (optionally, using given custom format) into fields returning a map from field name to its value.

RETURN apoc.date.fields('2015-03-25 03:15:59')

The following returns the fields in a date and time: 

RETURN apoc.date.fields('2015-01-02 03:04:05 EET', 'yyyy-MM-dd HH:mm:ss zzz') AS output;

Table 10.9. Results
Output

{ 'weekdays': 5, 'years': 2015, 'seconds': 5, 'zoneid': 'EET', 'minutes': 4, 'hours': 3, 'months': 1, 'days': 2 }

The following returns the fields in a date: 

RETURN apoc.date.fields('2015/01/02_EET', 'yyyy/MM/dd_z') AS output;

Table 10.10. Results
Output

{ 'weekdays': 5, 'years': 2015, 'zoneid': 'EET', 'months': 1, 'days': 2 }

10.2.6. Notes on formats:

  • the default format is yyyy-MM-dd HH:mm:ss
  • if the format pattern doesn’t specify timezone, formatter considers dates to belong to the UTC timezone
  • if the timezone pattern is specified, the timezone is extracted from the date string, otherwise an error will be reported
  • the to/fromSeconds timestamp values are in POSIX (Unix time) system, i.e. timestamps represent the number of seconds elapsed since 00:00:00 UTC, Thursday, 1 January 1970
  • the full list of supported formats is described in SimpleDateFormat JavaDoc

10.2.7. Reading single datetime field from UTC Epoch:

Extracts the value of one field from a datetime epoch.

RETURN apoc.date.field(12345)

Following fields are supported:

Result field Represents

'years'

year

'months'

month of year

'days'

day of month (default)

'hours'

hour of day

'minutes'

minute of hour

'seconds'

second of minute

'millis'

milliseconds of a second

The following returns the day of the month of the timestamp: 

RETURN apoc.date.field(12345) AS output;

Table 10.11. Results
Output

1

The following returns the year of the timestamp: 

RETURN apoc.date.field(12345, 'years') AS output;

Table 10.12. Results
Output

1970