elasticsearch/docs/reference/esql/functions/description/date_diff.asciidoc

// 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.

[cols="^,^",role="styled"]
|===
2+h|Datetime difference units

s|unit
s|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}.