date.truncate

Description

Truncates a date/time value to the specified unit (e.g., day, month, year), setting all smaller units to their minimum values. All operations are UTC-based.

Syntax

flex.date.truncate(datetime, unit)

Parameters

Parameter	Type	Required	Description
datetime	Date/number/string	Yes	The date/time value to truncate
unit	string	Yes	The unit to truncate to

Supported Units

Unit	Description	Truncates To
'minute'	Truncate to start of minute	Sets seconds and milliseconds to 0
'hour'	Truncate to start of hour	Sets minutes, seconds, and milliseconds to 0
'day'	Truncate to start of day	Sets time to 00:00:00.000
'week'	Truncate to start of week	Sets to Monday 00:00:00.000
'month'	Truncate to start of month	Sets to 1st day at 00:00:00.000
'quarter'	Truncate to start of quarter	Sets to 1st day of quarter month at 00:00:00.000
'year'	Truncate to start of year	Sets to January 1st at 00:00:00.000

Returns

Type: Date

A new Date object truncated to the specified unit. Returns null if input is invalid. Returns the original date if unit is unrecognized.

Examples

Example 1: Truncate to Day

WITH datetime('2024-03-15T14:30:45Z') AS dt
RETURN flex.date.truncate(dt, 'day') AS truncated

Output:

truncated
--------------------------
2024-03-15T00:00:00.000Z

Example 2: Truncate to Month

WITH datetime('2024-03-15T14:30:45Z') AS dt
RETURN flex.date.truncate(dt, 'month') AS truncated

Output:

truncated
--------------------------
2024-03-01T00:00:00.000Z

Example 3: Group Events by Week

MATCH (e:Event)
WITH flex.date.truncate(e.timestamp, 'week') AS week, count(*) AS eventCount
RETURN week, eventCount
ORDER BY week

Example 4: Monthly Aggregation

MATCH (s:Sale)
WITH flex.date.truncate(s.date, 'month') AS month, sum(s.amount) AS totalSales
RETURN month, totalSales
ORDER BY month

Example 5: Quarter Analysis

MATCH (o:Order)
WITH flex.date.truncate(o.orderDate, 'quarter') AS quarter, count(*) AS orders
RETURN quarter, orders
ORDER BY quarter DESC

Notes

• Returns null for invalid date inputs
• All operations use UTC timezone
• Week starts on Monday (ISO week convention)
• Quarters: Q1 (Jan-Mar), Q2 (Apr-Jun), Q3 (Jul-Sep), Q4 (Oct-Dec)
• Unknown units return the original normalized date
• Useful for time-series aggregation and bucketing

See Also

• date.format - Format date to string
• date.parse - Parse string to date
• date.toTimeZone - Convert date to timezone