date_trunc

Generic Description

Truncates a temporal value to a named unit. It is documented separately because time construction, sequence ordering, window parameters, and as-of behavior materially change analytical meaning.

Simple example:

RETURN date_trunc('day', datetime('2025-03-01T12:34:56Z'))

Consumer-Level Explanation

Use it for stable time buckets such as day, week, or month. Prefer this function when the temporal assumption should be visible to the planner, especially for event streams, freshness checks, and sequence features.

More Detailed Explanation

date_trunc belongs to the temporal construction, conversion, or extraction surface. Use it to make time semantics explicit in the query text: whether a value is date-only, time-only, timestamp-like, duration-like, current-time dependent, or bucketed to a chosen calendar unit.

Advanced Example

This example names the event stream and operational context before applying date_trunc, which helps planner tooling preserve the intended sequence semantics.

MATCH (u:User)-[e:VIEWED]->(d:Document)
TIME e.ts BETWEEN datetime('2025-01-01T00:00:00Z') AND datetime('2025-02-01T00:00:00Z')
WITH u, e, d,
     unpivot(properties(d.metadata)) AS metadata_rows,
     date_trunc('day', e.ts) AS day_bucket,
     date_trunc(e.ts) AS focused_value
RETURN u.user_id, d.title, day_bucket, metadata_rows, focused_value
LIMIT 10

Real Use Cases

Real Limitations And Tradeoffs