# DATETIME\_DELTA

The function DATETIME\_DELTA returns returns the number of total years, total months, total days, total hours, total minutes, total seconds, and total milliseconds between two DateTimes.

This function takes two [DateTimes](../../variable-data-types/the-datetime-variable-data-type) as input. It returns he number of total years, total months, total days, total hours, total minutes, total seconds, and total milliseconds between the two DateTimes. This output is a is formatted like another [DateTimes](../../variable-data-types/the-datetime-variable-data-type), but, unlike most [DateTimes](../../variable-data-types/the-datetime-variable-data-type), it does not express a valid time or day. Calcuation takes into account irregularities such as daylight savings time and leap years as well as timezone discrepancies.

#### Declaration

```javascript
DATETIME_DELTA(datetime1, datetime2) -> delta
```

&#x20;

#### Parameters

**datetime1** (required, type: _DateTime_) Any DateTime.

**datetime2** (required, type: _DateTime_) Any DateTime.

#### Return Values

**delta** (type: _Datetime_) The number of total years, total months, total days, total hours, total minutes, total seconds, and total milliseconds between **datetime1** and **datetime2**. Calculations takes into account timezone discrepancies as well as irregularities such as daylight savings time and leap years. Unlike most [DateTimes](../../variable-data-types/the-datetime-variable-data-type), **delta** does not express a valid time or day.

#### Examples

Assume the following examples have access to the following DateTime values:

```javascript
example_date_and_time1 ={  
 "date": {  
  "day": 16,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 9,  
  "minute": 33,  
  "second": 10,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}  
  
example_date_and_time2 = {  
 "date": {  
  "day": 26,  
  "month": 4,  
  "year": 2019  
 },  
 "time": {  
  "hour": 16,  
  "minute": 55,  
  "second": 46,  
  "millisecond": 500  
 },  
 "timeZone": "America/Anguilla"  
}
```

The following example returns the the number of years, months, years, hours, minutes, seconds, and milliseconds between **example\_date\_and\_time1** and **example\_date\_and\_time2**. Note that the values associated with "day", "month", "hour", "minute", "second", and millisecond" are too large to be valid values describing a real [DateTimes](../../variable-data-types/the-datetime-variable-data-type) rather, the describe the total number of days, months, hours, minutes, seconds and milliseconds (respectively) between the two given DateTimes. Note also that took the different timezones of **example\_date\_and\_time1** and **example\_date\_and\_time2**, even though the returned result appears at first glance to be in UTC:

```javascript
DATETIME_DELTA(example_date_and_time1, example_date_and_time2) = {  
 "date": {  
  "day": 720,  
  "month": 23,  
  "year": 1  
 },  
 "time": {  
  "hour": 17292,  
  "minute": 1037557,  
  "second": 62253443,  
  "millisecond": 62253443500  
 },  
 "timeZone": "UTC"  
}
```

DATETIME\_DELTA returns the absolute difference between the given DateTimes; it does not matter which is given first. The following example returns the the number of days, months, years, hours, minutes, seconds, and milliseconds between **example\_date\_and\_time2** and **example\_date\_and\_time1**; note that the output is the same as the above example, even though the DateTime values are given in reverse order:

```javascript
DATETIME_DELTA(example_date_and_time2, example_date_and_time1) = {  
 "date": {  
  "day": 720,  
  "month": 23,  
  "year": 1  
 },  
 "time": {  
  "hour": 17292,  
  "minute": 1037557,  
  "second": 62253443,  
  "millisecond": 62253443500  
 },  
 "timeZone": "UTC"  
}
```

&#x20;

#### Discussion

The DateTime returned by DATETIME\_DELTA does not contain conventional DateTime information; while it is technically possible to use it as DateTime input in functions such as [FORMAT\_DATETIME](format_datetime) or [TIMESTAMP\_FROM\_DATETIME](timestamp_from_datetime), the output returned in such cases will not be meaningful. To avoid such confusion, it is best practice to use DATETIME\_DELTA in tandem with the [DAY](day), [MONTH](month), [YEAR](year), [HOUR](hour), [MINUTE](minute), or [SECOND](second) function. (There is no analogous MILLISECOND function; such small differences in time are effectively negligible in the context of real-world apps.) Examples can be found below:&#x20;

```javascript
DAY(DATETIME_DELTA(datetime1, datetime2)) -> day_delta
```

```javascript
MONTH(DATETIME_DELTA(datetime1, datetime2)) -> month_delta
```

```javascript
YEAR(DATETIME_DELTA(datetime1, datetime2)) -> year_delta
```

```javascript
HOUR(DATETIME_DELTA(datetime1, datetime2)) -> hour_delta
```

```javascript
MINUTE(DATETIME_DELTA(datetime1, datetime2)) -> minute_delta
```

```javascript
SECOND(DATETIME_DELTA(datetime1, datetime2)) -> second_delta
```

This returns a single [Number](../../variable-data-types/the-number-variable-data-type): the days, months, years, hours, minutes, or seconds, respectively, between the two DateTimes. &#x20;

Assume the following examples have access to **example\_date\_and\_time1** and **example\_date\_and\_time2** from the Examples section. The isolated difference between days, months, years, hours, minutes, or seconds (respectively) between them can be found as follows:

```javascript
DAY(DATETIME_DELTA(datetime1, datetime2)) -> 720
```

```javascript
MONTH(DATETIME_DELTA(datetime1, datetime2)) -> 23
```

```javascript
YEAR(DATETIME_DELTA(datetime1, datetime2)) -> 1
```

```javascript
HOUR(DATETIME_DELTA(datetime1, datetime2)) -> 17292
```

```javascript
MINUTE(DATETIME_DELTA(datetime1, datetime2)) -> 1037557
```

```javascript
SECOND(DATETIME_DELTA(datetime1, datetime2)) -> 62253443
```
