Date and Time Conversions

Dates and times can show up in a variety of formats and configurations, often requiring translations or conversions for data storage systems, reports, web pages, and more. The APOC date functions allow users to take these Long or String values and manipulate them for different types of format requirements.

If you need to manipulate Date object types into other formats, see Temporal Functions.

Notes on formats for dates and times:

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

Procedure Overview

The table below describes the available procedures:

type qualified name signature description

type	qualified name	signature	description
function	`apoc.date.add`	`apoc.date.add(time :: INTEGER?, unit :: STRING?, addValue :: INTEGER?, addUnit :: STRING?) :: (INTEGER?)`	apoc.date.add(12345, 'ms', -365, 'd') given a timestamp in one time unit, adds a value of the specified time unit
function	`apoc.date.convert`	`apoc.date.convert(time :: INTEGER?, unit :: STRING?, toUnit :: STRING?) :: (INTEGER?)`	apoc.date.convert(12345, 'ms', 'd') convert a timestamp in one time unit into one of a different time unit
function	`apoc.date.convertFormat`	`apoc.date.convertFormat(temporal :: STRING?, currentFormat :: STRING?, convertTo = yyyy-MM-dd :: STRING?) :: (STRING?)`	apoc.date.convertFormat('Tue, 14 May 2019 14:52:06 -0400', 'rfc_1123_date_time', 'iso_date_time') convert a String of one date format into a String of another date format.
function	`apoc.date.currentTimestamp`	`apoc.date.currentTimestamp() :: (INTEGER?)`	apoc.date.currentTimestamp() - returns System.currentTimeMillis()
function	`apoc.date.field`	`apoc.date.field(time :: INTEGER?, unit = d :: STRING?, timezone = UTC :: STRING?) :: (INTEGER?)`	apoc.date.field(12345,('ms\|s\|m\|h\|d\|month\|year'),('TZ')
function	`apoc.date.fields`	`apoc.date.fields(date :: STRING?, pattern = yyyy-MM-dd HH:mm:ss :: STRING?) :: (MAP?)`	apoc.date.fields('2012-12-23',('yyyy-MM-dd')) - return columns and a map representation of date parsed with the given format with entries for years,months,weekdays,days,hours,minutes,seconds,zoneid
function	`apoc.date.format`	`apoc.date.format(time :: INTEGER?, unit = ms :: STRING?, format = yyyy-MM-dd HH:mm:ss :: STRING?, timezone = :: STRING?) :: (STRING?)`	apoc.date.format(12345,('ms\|s\|m\|h\|d'),('yyyy-MM-dd HH:mm:ss zzz'),('TZ')) get string representation of time value optionally using the specified unit (default ms) using specified format (default ISO) and specified time zone (default current TZ)
function	`apoc.date.fromISO8601`	`apoc.date.fromISO8601(time :: STRING?) :: (INTEGER?)`	apoc.date.fromISO8601('yyyy-MM-ddTHH:mm:ss.SSSZ') return number representation of time in EPOCH format
function	`apoc.date.parse`	`apoc.date.parse(time :: STRING?, unit = ms :: STRING?, format = yyyy-MM-dd HH:mm:ss :: STRING?, timezone = :: STRING?) :: (INTEGER?)`	apoc.date.parse('2012-12-23','ms\|s\|m\|h\|d','yyyy-MM-dd') parse date string using the specified format into the specified time unit
function	`apoc.date.parseAsZonedDateTime`	`apoc.date.parseAsZonedDateTime(time :: STRING?, format = yyyy-MM-dd HH:mm:ss :: STRING?, timezone = UTC :: STRING?) :: (DATETIME?)`	apoc.date.parseAsZonedDateTime('2012-12-23 23:59:59','yyyy-MM-dd HH:mm:ss', 'UTC-hour-offset') parse date string using the specified format to specified timezone
function	`apoc.date.systemTimezone`	`apoc.date.systemTimezone() :: (STRING?)`	apoc.date.systemTimezone() returns the system timezone display name
function	`apoc.date.toISO8601`	`apoc.date.toISO8601(time :: INTEGER?, unit = ms :: STRING?) :: (STRING?)`	apoc.date.toISO8601(12345,('ms\|s\|m\|h\|d') return string representation of time in ISO8601 format
function	`apoc.date.toYears`	`apoc.date.toYears(value :: ANY?, format = yyyy-MM-dd HH:mm:ss :: STRING?) :: (FLOAT?)`	toYears(timestamp) or toYears(date[,format]) converts timestamp into floating point years

function

apoc.date.add

apoc.date.add(time :: INTEGER?, unit :: STRING?, addValue :: INTEGER?, addUnit :: STRING?) :: (INTEGER?)

apoc.date.add(12345, 'ms', -365, 'd') given a timestamp in one time unit, adds a value of the specified time unit

function

apoc.date.convert

apoc.date.convert(time :: INTEGER?, unit :: STRING?, toUnit :: STRING?) :: (INTEGER?)

apoc.date.convert(12345, 'ms', 'd') convert a timestamp in one time unit into one of a different time unit

function

apoc.date.convertFormat

apoc.date.convertFormat(temporal :: STRING?, currentFormat :: STRING?, convertTo = yyyy-MM-dd :: STRING?) :: (STRING?)

apoc.date.convertFormat('Tue, 14 May 2019 14:52:06 -0400', 'rfc_1123_date_time', 'iso_date_time') convert a String of one date format into a String of another date format.

function

apoc.date.currentTimestamp

apoc.date.currentTimestamp() :: (INTEGER?)

apoc.date.currentTimestamp() - returns System.currentTimeMillis()

function

apoc.date.field

apoc.date.field(time :: INTEGER?, unit = d :: STRING?, timezone = UTC :: STRING?) :: (INTEGER?)

apoc.date.field(12345,('ms|s|m|h|d|month|year'),('TZ')

function

apoc.date.fields

apoc.date.fields(date :: STRING?, pattern = yyyy-MM-dd HH:mm:ss :: STRING?) :: (MAP?)

apoc.date.fields('2012-12-23',('yyyy-MM-dd')) - return columns and a map representation of date parsed with the given format with entries for years,months,weekdays,days,hours,minutes,seconds,zoneid

function

apoc.date.format

apoc.date.format(time :: INTEGER?, unit = ms :: STRING?, format = yyyy-MM-dd HH:mm:ss :: STRING?, timezone = :: STRING?) :: (STRING?)

apoc.date.format(12345,('ms|s|m|h|d'),('yyyy-MM-dd HH:mm:ss zzz'),('TZ')) get string representation of time value optionally using the specified unit (default ms) using specified format (default ISO) and specified time zone (default current TZ)

function

apoc.date.fromISO8601

apoc.date.fromISO8601(time :: STRING?) :: (INTEGER?)

apoc.date.fromISO8601('yyyy-MM-ddTHH:mm:ss.SSSZ') return number representation of time in EPOCH format

function

apoc.date.parse

apoc.date.parse(time :: STRING?, unit = ms :: STRING?, format = yyyy-MM-dd HH:mm:ss :: STRING?, timezone = :: STRING?) :: (INTEGER?)

apoc.date.parse('2012-12-23','ms|s|m|h|d','yyyy-MM-dd') parse date string using the specified format into the specified time unit

function

apoc.date.parseAsZonedDateTime

apoc.date.parseAsZonedDateTime(time :: STRING?, format = yyyy-MM-dd HH:mm:ss :: STRING?, timezone = UTC :: STRING?) :: (DATETIME?)

apoc.date.parseAsZonedDateTime('2012-12-23 23:59:59','yyyy-MM-dd HH:mm:ss', 'UTC-hour-offset') parse date string using the specified format to specified timezone

function

apoc.date.systemTimezone

apoc.date.systemTimezone() :: (STRING?)

apoc.date.systemTimezone() returns the system timezone display name

function

apoc.date.toISO8601

apoc.date.toISO8601(time :: INTEGER?, unit = ms :: STRING?) :: (STRING?)

apoc.date.toISO8601(12345,('ms|s|m|h|d') return string representation of time in ISO8601 format

function

apoc.date.toYears

apoc.date.toYears(value :: ANY?, format = yyyy-MM-dd HH:mm:ss :: STRING?) :: (FLOAT?)

toYears(timestamp) or toYears(date[,format]) converts timestamp into floating point years

`apoc.date.add`

This function can add or subtract time unit values to or from dates in the epoch format.

signature

signature
`apoc.date.add(time :: INTEGER?, unit :: STRING?, addValue :: INTEGER?, addUnit :: STRING?) :: (INTEGER?)`

apoc.date.add(time :: INTEGER?, unit :: STRING?, addValue :: INTEGER?, addUnit :: STRING?) :: (INTEGER?)

It accepts the following parameters:

Table 1. Config
name	type	description	potential values
time	Integer	the date value (in epoch integer format) to operate upon
unit	String	the specificity of the input value	`ms,s,m,h,d` or long forms (`millis,seconds,minutes,hours,days`)
addValue	Integer	the number to add or subtract from the time
addUnit	String	the unit type to add or subtract	`ms,s,m,h,d` or long forms

`apoc.date.convert`

This function converts date values of one time unit to date values of a different time unit.

signature

signature
`apoc.date.convert(time :: INTEGER?, unit :: STRING?, toUnit :: STRING?) :: (INTEGER?)`

apoc.date.convert(time :: INTEGER?, unit :: STRING?, toUnit :: STRING?) :: (INTEGER?)

It accepts the following parameters:

Table 2. Config
name	type	description	potential values
time	Integer	the date value (in epoch integer format) to operate upon
unit	String	the specificity of the input value	`ms,s,m,h,d` or long forms (`millis,seconds,minutes,hours,days`)
toUnit	String	the unit type for the output value	`ms,s,m,h,d` or long forms

`apoc.date.convertFormat`

This function converts date strings of one format to date strings of a different format.

signature

signature
`apoc.date.convertFormat(temporal :: STRING?, currentFormat :: STRING?, convertTo = yyyy-MM-dd :: STRING?) :: (STRING?)`

apoc.date.convertFormat(temporal :: STRING?, currentFormat :: STRING?, convertTo = yyyy-MM-dd :: STRING?) :: (STRING?)

It accepts the following parameters:

Table 3. Config
name	type	description	potential values
temporal	String	the date string that needs converted
currentFormat	String	the format of the input date string	see the Java documentation for full list (under Patterns for Formatting and Parsing)
convertTo	String	the format for the output temporal type	can be specified manually with Java formats or as built-in formats

`apoc.date.currentTimestamp`

This function returns the current timestamp from the system at the time it is called. It provides the System.currentTimeMillis(), which is current throughout transaction execution, and is different from Cypher’s timestamp() function, which does not update within a transaction.

signature

signature
`apoc.date.currentTimestamp() :: (INTEGER?)`

apoc.date.currentTimestamp() :: (INTEGER?)

It accepts no parameters.

`apoc.date.field`

This function extracts the value of one field from a date in epoch format.

signature

signature
`apoc.date.field(time :: INTEGER?, unit = d :: STRING?, timezone = UTC :: STRING?) :: (INTEGER?)`

apoc.date.field(time :: INTEGER?, unit = d :: STRING?, timezone = UTC :: STRING?) :: (INTEGER?)

In version 3.4 Neo4j introduced temporal data types, which are the recommended way of representing dates in Neo4j. Fields of a temporal type can be retrieved using Cypher’s instance.field function. (e.g. datetime({epochMillis: dateInteger}).year) See the Cypher documentation for more details on the syntax.

If, however, you still need to convert timestamp formats, this procedure provides that functionality.

It accepts the following parameters:

Table 4. Config
name	type	description	potential values
time	Integer	the date value (in epoch integer format) to operate upon
unit	String	the specificity of the input value	`ms,s,m,h,d` or long forms (`millis,seconds,minutes,hours,days`)
timezone	String	the timezone of the resulting date string	can be specified with GMT or database (text) name, as listed for timezones

`apoc.date.fields`

This function extracts values of all fields from a date in epoch format and returns the columns and a map representation.

signature

signature
`apoc.date.fields(date :: STRING?, pattern = yyyy-MM-dd HH:mm:ss :: STRING?) :: (MAP?)`

apoc.date.fields(date :: STRING?, pattern = yyyy-MM-dd HH:mm:ss :: STRING?) :: (MAP?)

If, however, you still need to convert timestamp formats, this procedure provides that functionality.

It accepts the following parameters:

Table 5. Config
name	type	description	potential values
date	String	the date string that needs formatted	date string in an ISO8601 standard format
pattern	String	the format of the input date string	see the Java documentation for full list (under Patterns for Formatting and Parsing)

`apoc.date.format`

This function converts dates in epoch format to date strings with a specified format.

signature

signature
`apoc.date.format(time :: INTEGER?, unit = ms :: STRING?, format = yyyy-MM-dd HH:mm:ss :: STRING?, timezone = :: STRING?) :: (STRING?)`

apoc.date.format(time :: INTEGER?, unit = ms :: STRING?, format = yyyy-MM-dd HH:mm:ss :: STRING?, timezone = :: STRING?) :: (STRING?)

It accepts the following parameters:

Table 6. Config
name	type	description	potential values
time	Integer	the date value (in epoch integer format) to operate upon
unit	String	the specificity of the input value	`ms,s,m,h,d` or long forms (`millis,seconds,minutes,hours,days`)
format	String	the format for the output date string	can be specified manually with Java formats or as built-in formats
timezone	String	the timezone of the resulting date string	can be specified with GMT or database (text) name, as listed for timezones

`apoc.date.fromISO8601`

This function converts date strings in an ISO8601 standard format to dates in epoch format.

signature

signature
`apoc.date.format(time :: INTEGER?, unit = ms :: STRING?, format = yyyy-MM-dd HH:mm:ss :: STRING?, timezone = :: STRING?) :: (STRING?)`

apoc.date.format(time :: INTEGER?, unit = ms :: STRING?, format = yyyy-MM-dd HH:mm:ss :: STRING?, timezone = :: STRING?) :: (STRING?)

It accepts the following parameters:

Table 7. Config
name	type	description	potential values
time	String	the date string that needs formatted	date string in an ISO8601 standard format

The date string timezone expects only a GMT+00:00 format of Z as the timezone specifier. Other timezone specifications are not supported by this procedure.

`apoc.date.parse`

This function parses a date string in one format and converts it to a date of the specified time unit in Epoch format.

signature

signature
`apoc.date.parse(time :: STRING?, unit = ms :: STRING?, format = yyyy-MM-dd HH:mm:ss :: STRING?, timezone = :: STRING?) :: (INTEGER?)`

apoc.date.parse(time :: STRING?, unit = ms :: STRING?, format = yyyy-MM-dd HH:mm:ss :: STRING?, timezone = :: STRING?) :: (INTEGER?)

It accepts the following parameters:

Table 8. Config
name	type	description	potential values
time	String	the date string that needs formatted	date string in an ISO8601 standard format
unit	String	the specificity desired for the output date value	`ms,s,m,h,d` or long forms (`millis,seconds,minutes,hours,days`)
format	String	the format of the date string to convert	see the Java documentation for full list (under Patterns for Formatting and Parsing)
timezone	String	the timezone of the resulting date string	can be specified with GMT or database (text) name, as listed for timezones

`apoc.date.parseAsZonedDateTime`

This function parses a date string in a specified format and converts it to a Neo4j-supported temporal type with date, time, and timezone.

This function has been renamed to apoc.temporal.toZonedDateTime and moved to the temporal section. See [temporal-conversions].

`apoc.date.systemTimezone`

This function returns the timezone display name of the system.

signature

signature
`apoc.date.systemTimezone() :: (STRING?)`

apoc.date.systemTimezone() :: (STRING?)

It accepts no parameters.

`apoc.date.toISO8601`

This function converts dates in epoch format to date strings in ISO8601 standard format.

signature

signature
`apoc.date.toISO8601(time :: INTEGER?, unit = ms :: STRING?) :: (STRING?)`

apoc.date.toISO8601(time :: INTEGER?, unit = ms :: STRING?) :: (STRING?)

It accepts the following parameters:

Table 9. Config
name	type	description	potential values
time	Integer	the date value (in epoch integer format) to operate upon
unit	String	the specificity of the input value	`ms,s,m,h,d` or long forms (`millis,seconds,minutes,hours,days`)

`apoc.date.toYears`

This function can make a couple of different conversions.

Convert dates in epoch millisecond format to the number of years that have passed since the Unix epoch time of January 1, 1970.
Convert date strings in specified formats to the number of years that have passed since the year 0.

signature

signature
`apoc.date.toISO8601(time :: INTEGER?, unit = ms :: STRING?) :: (STRING?)`

apoc.date.toISO8601(time :: INTEGER?, unit = ms :: STRING?) :: (STRING?)

It accepts the following parameters for each conversion:

Table 10. Config - epoch to years
name	type	description	potential values
value	Integer	the date value (in epoch millisecond integer format) to operate upon	NOTE: the timestamp must be in `ms` format!

Table 11. Config - string date to years
name	type	description	potential values
value	String	the date string that needs formatted	date string in an ISO8601 standard format
format	String	the format of the date string to convert	see the Java documentation for full list (under Patterns for Formatting and Parsing)