## DATE_DIFF

The `DATE_DIFF` function subtracts the `startTimestamp` from the `endTimestamp` and returns the difference in multiples of a specified unit. If `startTimestamp` is later than the `endTimestamp`, negative values are returned. 

Note that while there is an overlap between the function’s supported units and ES|QL’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 Elasticsearch.

### Syntax

`DATE_DIFF(unit, startTimestamp, endTimestamp)`

#### Parameters

- `unit`: Time difference unit
- `startTimestamp`: A string representing a start timestamp
- `endTimestamp`: A string representing an end timestamp

### Examples

Here are a couple of examples of how to use the `DATE_DIFF` function in ES|QL queries:

```esql
ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-02T11:00:00.001Z")
| EVAL dd_ms = DATE_DIFF("microseconds", date1, date2)
```

In this example, the `DATE_DIFF` function is used to calculate the difference in microseconds between two timestamps.

```esql
ROW date1 = TO_DATETIME("2023-12-02T11:00:00.000Z"), date2 = TO_DATETIME("2023-12-03T11:00:00.000Z")
| EVAL dd_days = DATE_DIFF("days", date1, date2)
```

In this second example, the `DATE_DIFF` function is used to calculate the difference in days between two timestamps.