Neo4j DateTime Zone ID Persistence and Local Conversion Limits

What Happens When You Compare a Zoned DateTime to a LocalDateTime?

In Neo4j, a DateTime always stores an instant in UTC together with the original zone ID or offset. A LocalDateTime has no zone information – it’s just a wall‑clock moment. When Cypher evaluates a comparison such as $dt = $ldt, Neo4j performs an implicit coercion of the LocalDateTime into a DateTime by applying the server’s default time zone (configured in neo4j.conf via dbms.timezone).

After coercion, the comparison is carried out on the two resulting UTC instants. The original zone ID of the DateTime is preserved during this process; it is not ignored or replaced by the local zone. Therefore:

• If the LocalDateTime represents the same instant as the DateTime when interpreted in the server’s default zone, the comparison returns true.
• Otherwise it returns false

Practical Verification Steps

1. Start Neo4j with a known default zone, e.g. dbms.timezone=UTC.

   # neo4j.conf
   dbms.timezone=UTC
   

2. In a Cypher session, create a DateTime with a non‑UTC zone ID:

   WITH datetime({ year:2026, month:10, day:10, hour:21, minute:13, second:25, zoneId:'America/New_York' }) AS dt
   RETURN dt;
   

3. Create a matching LocalDateTime for the same wall‑clock time:

   WITH localdatetime({ year:2026, month:10, day:10, hour:21, minute:13, second:25 }) AS ldt
   RETURN ldt;
   

4. Compare them:

   RETURN $dt = $ldt;
   

5. Observe the result. With UTC as the server zone, the comparison will be false because 21:13:25 in New York is 01:13:25 UTC the next day. Changing the server zone to America/New_York would make the comparison return true.

Key Take‑aways

• Neo4j does not silently drop the zone ID from a DateTime when comparing to a LocalDateTime.
• The implicit conversion uses the server’s default zone; this is why the comparison outcome can vary across environments.
• To avoid surprises, either set dbms.timezone to the zone you intend to use for comparisons, or explicitly convert the LocalDateTime to the desired zone using datetime({… zoneId:… }) before comparing.

Missing Diagnostic Detail

If you’re unsure what the server’s default time zone is in your deployment, run:

RETURN apoc.meta.getConfig('dbms.timezone');

This will reveal the current zone and help determine whether your comparison logic needs adjustment.