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:

Qualified Name Type

Qualified Name	Type
apoc.date.add `apoc.date.add(time INTEGER, unit STRING, addValue INTEGER, addUnit STRING)` - adds a unit of specified time to the given timestamp.	`Function`
apoc.date.convert `apoc.date.convert(time INTEGER, unit STRING, toUnit STRING)` - converts the given timestamp from one time unit into a timestamp of a different time unit.	`Function`
apoc.date.convertFormat `apoc.date.convertFormat(temporal STRING, currentFormat STRING, convertTo STRING)` - converts a `STRING` of one type of date format into a `STRING` of another type of date format.	`Function`
apoc.date.currentTimestamp `apoc.date.currentTimestamp()` - returns the current Unix epoch timestamp in milliseconds.	`Function`
apoc.date.field `apoc.date.field(time INTEGER, unit STRING, timezone STRING)` - returns the value of one field from the given date time.	`Function`
apoc.date.fields `apoc.date.fields(date STRING, pattern STRING)` - splits the given date into fields returning a `MAP` containing the values of each field.	`Function`
apoc.date.format `apoc.date.format(time INTEGER, unit STRING, format STRING, timezone STRING)` - returns a `STRING` representation of the time value. The time unit (default: ms), date format (default: ISO), and time zone (default: current time zone) can all be changed.	`Function`
apoc.date.fromISO8601 `apoc.date.fromISO8601(time STRING)` - converts the given date `STRING` (ISO8601) to an `INTEGER` representing the time value in milliseconds.	`Function`
apoc.date.parse `apoc.date.parse(time STRING, unit STRING, format STRING, timezone STRING)` - parses the given date `STRING` from a specified format into the specified time unit.	`Function`
apoc.date.systemTimezone `apoc.date.systemTimezone()` - returns the display name of the system time zone (e.g. Europe/London).	`Function`
apoc.date.toISO8601 `apoc.date.toISO8601(time INTEGER, unit STRING)` - returns a `STRING` representation of a specified time value in the ISO8601 format.	`Function`
apoc.date.toYears `apoc.date.toYears(value ANY, format STRING)` - converts the given timestamp or the given date into a `FLOAT` representing years.	`Function`

apoc.date.add
apoc.date.add(time INTEGER, unit STRING, addValue INTEGER, addUnit STRING) - adds a unit of specified time to the given timestamp.

Function

apoc.date.convert
apoc.date.convert(time INTEGER, unit STRING, toUnit STRING) - converts the given timestamp from one time unit into a timestamp of a different time unit.

Function

apoc.date.convertFormat
apoc.date.convertFormat(temporal STRING, currentFormat STRING, convertTo STRING) - converts a STRING of one type of date format into a STRING of another type of date format.

Function

apoc.date.currentTimestamp
apoc.date.currentTimestamp() - returns the current Unix epoch timestamp in milliseconds.

Function

apoc.date.field
apoc.date.field(time INTEGER, unit STRING, timezone STRING) - returns the value of one field from the given date time.

Function

apoc.date.fields
apoc.date.fields(date STRING, pattern STRING) - splits the given date into fields returning a MAP containing the values of each field.

Function

apoc.date.format
apoc.date.format(time INTEGER, unit STRING, format STRING, timezone STRING) - returns a STRING representation of the time value. The time unit (default: ms), date format (default: ISO), and time zone (default: current time zone) can all be changed.

Function

apoc.date.fromISO8601
apoc.date.fromISO8601(time STRING) - converts the given date STRING (ISO8601) to an INTEGER representing the time value in milliseconds.

Function

apoc.date.parse
apoc.date.parse(time STRING, unit STRING, format STRING, timezone STRING) - parses the given date STRING from a specified format into the specified time unit.

Function

apoc.date.systemTimezone
apoc.date.systemTimezone() - returns the display name of the system time zone (e.g. Europe/London).

Function

apoc.date.toISO8601
apoc.date.toISO8601(time INTEGER, unit STRING) - returns a STRING representation of a specified time value in the ISO8601 format.

Function

apoc.date.toYears
apoc.date.toYears(value ANY, format STRING) - converts the given timestamp or the given date into a FLOAT representing years.

Function

`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

View usage examples

`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

View usage examples

`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

View usage examples

`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.

View usage examples

`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

Neo4j 3.4 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

View usage examples

`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

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 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)

View usage examples

`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

View usage examples

`apoc.date.fromISO8601`

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

signature

signature
`apoc.date.fromISO8601(time :: STRING) :: INTEGER`

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

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.

View usage examples

`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

View usage examples

`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.

View usage examples

`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`)

View usage examples

`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.toYears(value :: ANY, format = yyyy-MM-dd HH:mm:ss :: STRING) :: FLOAT`

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

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)

View usage examples