How to Use Neo4j string to datetime – With Examples

In searching Neo4j string to datetime, most people are either wondering if they have somehow missed the datetime() function in Neo4j, or if not, how to best accomplish the goal of creating formatted datetime objects, from a string, in the most straightforward way within Neo4j.

Neo4j string to datetime – Background

Every database and programming language is able to store and parse dates from different formats and data types in one way or another. Each of them have their own structures and libraries to work with date/time formats, but it can vary quite a lot.

Not surprisingly, Neo4j has its own set of capabilities and approaches for handling these occasionally complex tasks. Aside from the core temporal (date/time) functions in Neo4j Cypher graph query language, the Neo4j date/time formatting capabilities are significantly augmented by the APOC library which has even more detailed date/time functions and procedures as well as powerful date/time formatting.

Temporal (Date/Time) Values in Neo4j – Overview

As of version 3.4, Neo4j string to datetime documentation points toward a standardized approach in order to streamline the development process. As of that version, Neo4j is more seamlessly handling temporal values, and now the underlying database supports storing these temporal values directly as properties on nodes as well as relationships.

The temporal data types in Cypher are based on the ISO 8601 date format, and it supports:

• categories of time: Date, Time, and Timezone
• temporal instants: Date, Time, Datetime, LocalTime, and LocalDatetime.
• formats: temporal operators and datetime operators

This approach enables Neo4j to separate the managing of temporal values into these two major groups of functions:

1. Temporal instant types function for the creation and manipulation of values for each temporal type —  Date, Time, LocalTime, DateTime, and LocalDateTime.
2. Durational functions allowing for the creation and manipulation of values for a Duration temporal type.

How to Use Neo4j string to datetime

Let’s now look at some specific examples:

In this first example, we can call the datetime function specifying the string, and it is automatically converted to an object of type datetime:

RETURN datetime() AS currentDateTime
"2022-07-14T10:02:28.192Z"

Or in this example using the date function, we show how to specify the timezone as an argument:

RETURN date({timezone: 'America/Los Angeles'}) AS currentDateInLosAngeles
"2022-04-01"

Oftentimes this is more than enough, but to accomplish even the most complex date/time operations, the Neo4j APOC Library enables even more, as shown in the following example:

RETURN apoc.date.fields('2023-03-01 03:04:05 EET', 'yyyy-MM-dd HH:mm:ss zzz')
{
  "hours": 3,
  "seconds": 5,
  "months": 3,
  "weekdays": 3,
  "minutes": 4,
  "days": 1,
  "zoneid": "EET",
  "years": 2023
}

Using these examples, one can see the depth of capability to handle strings with date/time formats of just about any kind, as shown in this example below as well:

RETURN apoc.date.fields('2023/03/01_EET', 'yyyy/MM/dd_z')
{
  "days": 1,
  "zoneid": "EET",
  "months": 3,
  "years": 2023,
  "weekdays": 3
}

Common Neo4j string to datetime Challenges – Solved with Examples

These capabilities for Neo4j string to datetime operations solve almost any Neo4j temporal data challenges. Some of the most common issues we see are developers struggling with are:

• Conversion between formatted dates and timestamps
  apoc.date.parse('2023/03/01 03:04:05',['ms'/'s'], ['yyyy/MM/dd HH:mm:ss'])
• Conversion of timestamps between different time units apoc.date.convert(12345, 'ms', 'd')
• Adding/subtracting time unit values to timestamps apoc.date.add(12345, 'ms', -365, 'd')
• Reading separate datetime fields apoc.date.fields('2023-03-01 03:04:07')
• reading single datetime fields from UTC epoch apoc.date.field(123456789, 'days')

Conclusion and Some Helpful Hints

Hopefully this article has given you all you need to understand and leverage the Neo4j string to datetime temporal capabilities. We end with some helpful hints as you work on your own temporal development requirements:

• The default Neo4j 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 ISO 8601 formats is well-described in SimpleDateFormat JavaDoc
• One last thing to keep in mind is that there may be specific project requirements where other approaches for duration could ultimately perform better, such as implementing a Julian calendar, something that is beyond the scope of this article.

More Tech Resources

• bolt://localhost:7687 (How to use bolt protocol to access your Neo4j Database)
• https://neo4j.com/docs/graph-data-science/1.8/management-ops/ (Find Neo4j v1.8 GDS Graph Management)
• What is ChatGPT? (A Complete Explanation)