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 Release

apoc.date.add

- given a timestamp in one time unit, adds a value of the specified time unit

Function

APOC Core

apoc.date.convert

- convert a timestamp in one time unit into one of a different time unit

Function

APOC Core

apoc.date.convertFormat

- convert a String of one date format into a String of another date format.

Function

APOC Core

apoc.date.currentTimestamp

- returns System.currentTimeMillis() at the time it was called. The value is current throughout transaction execution, and is different from Cypher’s timestamp() function, which does not update within a transaction.

Function

APOC Core

apoc.date.field

Function

APOC Core

apoc.date.fields

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

apoc.date.format

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

apoc.date.fromISO8601

- return number representation of time in EPOCH format

Function

APOC Core

apoc.date.parse

- parse date string using the specified format into the specified time unit

Function

APOC Core

apoc.date.parseAsZonedDateTime

- parse date string using the specified format to specified timezone

Function

APOC Core

apoc.date.systemTimezone

- returns the system timezone display name

Function

APOC Core

apoc.date.toISO8601

- return string representation of time in ISO8601 format

Function

APOC Core

apoc.date.toYears

- converts timestamp into floating point years

Function

APOC Core

apoc.date.add

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

signature

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

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

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

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

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

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)

apoc.date.format

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

signature

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

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

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 deprecated by apoc.temporal.toZonedTemporal, therefore it’s recommended to use that one instead. See Temporal Functions.

apoc.date.systemTimezone

This function returns the timezone display name of the system.

signature

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

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.

  1. Convert dates in epoch millisecond format to the number of years that have passed since the Unix epoch time of January 1, 1970.

  2. Convert date strings in specified formats to the number of years that have passed since the year 0.

signature

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)