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