GraphAcademy

Using Neo4j with Java

The Driver

Handling results

Best practices

Dates and times

Temporal types

Temporal types in Neo4j are a combination of date, time and timezone elements.

Learn how to interact with Neo4j using the Neo4j Java DriverTemporal Types
Type Description Date? Time? Timezone?

Date

A tuple of Year, Month and Day

Y

Time

The time of the day with a UTC offset

Y

Y

LocalTime

A time without a timezone

Y

DateTime

A combination of Date and Time

Y

Y

Y

LocalDateTime

A combination of Date and Time without a timezone

Y

Y

Writing temporal types

java
import java.time.ZonedDateTime;
import java.time.ZoneId;
String dtstring="2024-05-15T14:30:00+02:00";
var datetime = ZonedDateTime.of(2024, 05, 15, 14, 30, 00, 0, ZoneId.of("+02:00"));
var result = driver.executableQuery("""
    CREATE (e:Event {
        startsAt: $datetime,              // (1)
        createdAt: datetime($dtstring),   // (2)
        updatedAt: datetime()             // (3)
    })
    RETURN e.startsAt AS startsAt, e.createdAt AS createdAt, e.updatedAt AS updatedAt;
    """)
    .withParameters(
        Map.of( "datetime", datetime, "dtstring", dtstring )) // (4)
    .execute();

When you write temporal types to the database, you can pass the object as a parameter to the query or cast the value within a Cypher statement.

This example demonstrates how to:

  1. Use a DateTime object as a parameter to the query (<4>)

  2. Cast an ISO 8601 format string within a Cypher statement

  3. Get the current date and time using the datetime() function.

You can cast the results of the query using the asZonedDateTime() method.

java
var event = result.records().get(0);
var startsAt = event.get("startsAt").asZonedDateTime();
var createdAt = event.get("createdAt").asZonedDateTime();
var updatedAt = event.get("updatedAt").asZonedDateTime();
System.out.println(startsAt);  // 2024-05-15T14:30+02:00
System.out.println(createdAt); // 2024-05-15T14:30+02:00
System.out.println(updatedAt); // today's date and time with +00:00 timezone

Reading temporal types

When reading temporal types from the database, you will receive an instance of the corresponding Java type.

java
var result = driver.executableQuery("""
    RETURN date() as date, time() as time,
        datetime() as datetime,
        toString(datetime()) as asString;
    """)
    .execute();

var records = result.records();
records.forEach(r -> {
    System.out.println(r.get("date"));      // neo4j.time.Date
    System.out.println(r.get("time"));      // neo4j.time.Time
    System.out.println(r.get("datetime"));  // neo4j.time.DateTime
    System.out.println(r.get("asString"));  // String
});

Working with Durations

java
import java.time.LocalDateTime;
import java.time.Duration;
var startsAt = LocalDateTime.now();
var eventLength = Duration.ofHours(1).plusMinutes(30);
var endsAt = startsAt.plus(eventLength);
var result = driver.executableQuery("""
    CREATE (e:Event { startsAt: $startsAt, endsAt: $endsAt,
        duration: $eventLength, // (1)
        interval: duration("PT1H30M") // (2)
    })
    RETURN e
    """)
    .withParameters(Map.of(
        "startsAt", startsAt, "endsAt", endsAt, "eventLength", eventLength
    ))
    .execute();

Durations represent a period of time and can be used for date arithmetic in both Java and Cypher. These types can also be created in Java or cast within a Cypher statement.

  1. Pass an instance of Java Duration to the query

  2. Use the duration() Cypher function to create a Duration object from an ISO 8601 format string

You can cast the results of the query by getting the properties from the node:

java
// Output results
var event = result.records().get(0).get("e").asNode();
System.out.println(event.get("startsAt")); // current datetime
System.out.println(event.get("endsAt"));   // current datetime + 1h 30m
System.out.println(event.get("duration")); // P0M0DT5400S (1h 30m in seconds)
System.out.println(event.get("interval")); // P0M0DT5400S (1h 30m in seconds)

Calculating durations

You can use the duration.between method to calculate the duration between two date or time objects.

Lesson Summary

In this lesson, you learned about working with temporal types in Neo4j using the Java driver:

  • Cypher provides classes for handling dates, times, and durations

  • You can pass temporal objects as parameters or create them within Cypher statements

  • When reading temporal values from Neo4j, they are automatically converted to the appropriate Java driver types

  • Durations can be used for date arithmetic in both Java and Cypher

Converting between driver and Cypher types

Because Neo4j was originally built in Java, nearly all of the Cypher data types align with Java’s standard library types. However, there are some exceptions, especially when it comes to temporal types. The main differences are with the timezone values. To see which Java and Cypher mappings are different, see the documentation page in the Java manual.