# DATE_DIFF

The DATE_DIFF function subtracts the `startTimestamp` from the `endTimestamp` and returns the difference in multiples of the specified `unit`. If `startTimestamp` is later than `endTimestamp`, the result will be negative.

## 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

Calculates the difference in microseconds between two datetime values.

```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)
```

Calculates the difference in years between several datetime values, counting only fully elapsed calendar years.

```esql
ROW end_23 = TO_DATETIME("2023-12-31T23:59:59.999Z"),
  start_24 = TO_DATETIME("2024-01-01T00:00:00.000Z"),
    end_24 = TO_DATETIME("2024-12-31T23:59:59.999")
| EVAL end23_to_start24 = DATE_DIFF("year", end_23, start_24)
| EVAL end23_to_end24   = DATE_DIFF("year", end_23, end_24)
| EVAL start_to_end_24  = DATE_DIFF("year", start_24, end_24)
```