elasticsearch/docs/reference/query-languages/esql/_snippets/functions/description/date_diff.md

% This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.

Description

Subtracts the startTimestamp from the endTimestamp and returns the difference in multiples of unit. If startTimestamp is later than the endTimestamp, negative values are returned.

Datetime difference units

unit	abbreviations
year	years, yy, yyyy
quarter	quarters, qq, q
month	months, mm, m
dayofyear	dy, y
day	days, dd, d
week	weeks, wk, ww
weekday	weekdays, dw
hour	hours, hh
minute	minutes, mi, n
second	seconds, ss, s
millisecond	milliseconds, ms
microsecond	microseconds, mcs
nanosecond	nanoseconds, ns

Note that while there is an overlap between the function’s supported units and {{esql}}’s supported time span literals, these sets are distinct and not interchangeable. Similarly, the supported abbreviations are conveniently shared with implementations of this function in other established products and not necessarily common with the date-time nomenclature used by {{es}}.