How to Use Neo4j string to datetime – With Examples

By Andriy Polukhin, Sr Developer

March 2, 2023

Tech Resources

Reading Time: 3 minutes

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.

Neo4j string to datetime
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

Graphable helps you make sense of your data by delivering expert analytics, data engineering, custom dev and applied data science services.

We are known for operating ethically, communicating well, and delivering on-time. With hundreds of successful projects across most industries, we have deep expertise in Financial Services, Life Sciences, Security/Intelligence, Transportation/Logistics, HighTech, and many others.

Thriving in the most challenging data integration and data science contexts, Graphable drives your analytics, data engineering, custom dev and applied data science success. Contact us to learn more about how we can help, or book a demo today.

Still learning? Check out a few of our introductory articles to learn more:

Additional discovery:

    We would also be happy to learn more about your current project and share how we might be able to help. Schedule a consultation with us today. We can also discuss pricing on these initial calls, including Neo4j pricing and Domo pricing. We look forward to speaking with you!


    Graphable helps you make sense of your data by delivering expert analytics, data engineering, custom dev and applied data science services.
     
    We are known for operating ethically, communicating well, and delivering on-time. With hundreds of successful projects across most industries, we have deep expertise in Financial Services, Life Sciences, Security/Intelligence, Transportation/Logistics, HighTech, and many others.
     
    Thriving in the most challenging data integration and data science contexts, Graphable drives your analytics, data engineering, custom dev and applied data science success. Contact us to learn more about how we can help, or book a demo today.

    We are known for operating ethically, communicating well, and delivering on-time. With hundreds of successful projects across most industries, we thrive in the most challenging data integration and data science contexts, driving analytics success.
    Contact us for more information: