# DATETIME\_FROM\_TIMESTAMP

**The TIMESTAMP\_FROM\_DATETIME function takes a timestamp – the number of milliseconds (or seconds) from 00:00:00 UTC, 1 January 1970 – and outputs the DateTime this number represents.**

This function takes any number as input. By default, this number represents some number of milliseconds from 00:00:00 UTC, 1 January 1970 (the Unix epoch), and DATE\_FROM\_TIMESTAMP will output the DateTime corresponding with this number. Said number can also be given in seconds, if indicated by the optional input string.

#### Declaration

```javascript
DATETIME_FROM_TIMESTAMP(number, unit_string) -> date_time
```

&#x20;

#### Parameters

**number** (required, type: _number_) A number of milliseconds (default) or seconds from 00:00:00 UTC, 1 January 1970, the Unix epoch.

**unit\_string** (optional, type: _string_) A string representation of the units of the input ("s" for seconds or "ms" for milliseconds). While DATETIME\_FROM\_TIMESTAMP will accept any string as valid input, the only strings it recognizes are "s" (which stands for "seconds") and "ms" (which stands for "milliseconds"). If given a string other than these two, it will run using the default units, milliseconds.&#x20;

####

#### Return Values

**date\_time** (type: _datetime_) The DateTime corresponding with the given number of milliseconds (or seconds) from 00:00:00 UTC, 1 January 1970, the Unix epoch.

#### Examples

The following example takes the number 1617240194000, interprets it as a 1617240194000 milliseconds after the Unix epoch, and outputs the corresponding DateTime. Note that the timezone of the resulting DateTime is UTC; this is timezone the DateTime resulting from DATETIME\_FROM\_TIMESTAMP will always be in:

```javascript
DATETIME_FROM_TIMESTAMP(1617240194000) -> {  
 "date": {  
  "day": 1,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 10,  
  "minute": 23,  
  "second": 14,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}
```

The above example interprets the given number as milliseconds from from the Unix epoch because milliseconds are the default unit. If given DATETIME\_FROM\_TIMESTAMP a number describing time from the Unix epoch in seconds that than milliseconds, units need to be declared explicitly by entering the string "s" (for "seconds") as the optional input variable **unit\_string**. The following example takes the number 1617240194, interprets it as a 1617240194 seconds after the Unix epoch, and outputs the corresponding DateTime:

```javascript
DATETIME_FROM_TIMESTAMP(1617240194, "s") -> {  
 "date": {  
  "day": 1,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 10,  
  "minute": 23,  
  "second": 14,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}
```

The optional variable **unit\_string** can also be used to explicitly specify that the input number is in milliseconds; in such cases, the output will be the same as though the default was used. The following example takes the number 1617240194000, interprets it as a 1617240194000 milliseconds ("ms") after the Unix epoch, and outputs the corresponding DateTime. Note that the output as the same as it was in the first example, when no optional input **unit\_string** was entered:

```javascript
DATETIME_FROM_TIMESTAMP(1617240194000, "ms") -> {  
 "date": {  
  "day": 1,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 10,  
  "minute": 23,  
  "second": 14,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}
```

Technically, the DATETIME\_FROM\_TIMESTAMP function will accept any string as a value for **unit\_string**, but only "s" and "ms" provide it with any signal. If any other string is given for **unit\_string**, DATETIME\_FROM\_TIMESTAMP will proceed to interpret the given number in milliseconds, the default units. The following example takes the number 1617240194000, interprets it as a 1617240194000 milliseconds after the Unix epoch, and outputs the corresponding DateTime: the same output that was returned in first the example, when the optional input **unit\_string** was not entered. The fact that the string "this is a string" is given as the **unit\_string** changes nothing:

```javascript
DATETIME_FROM_TIMESTAMP(1617240194000, "ms") -> {  
 "date": {  
  "day": 1,  
  "month": 4,  
  "year": 2021  
 },  
 "time": {  
  "hour": 10,  
  "minute": 23,  
  "second": 14,  
  "millisecond": 0  
 },  
 "timeZone": "UTC"  
}
```

&#x20;

#### Discussion

DATETIME\_FROM\_TIMESTAMP can be thought of as the opposite of [TIMESTAMP\_FROM\_DATETIME](timestamp_from_datetime); this is, assuming the giving DateTime is in the UTC timezone (call our example **date\_time**), DATETIME\_FROM\_TIMESTAMP can be used to undo what TIMESTAMP\_FROM\_DATETIME did, like so:

```javascript
DATETIME_FROM_TIMESTAMP(TIMESTAMP_FROM_DATETIME(date_time)) -> date_time
```

DATETIME\_FROM\_TIMESTAMP always returns DateTimes in UTC, and so the above example does not work out perfectly if **date\_time** is not initially given in the UTC timezone. Crucially, however, the given DateTime and the return DateTime will refer to the same time in an absolute sense; it is only the formatting that may be slightly different due to timezone shifts.

00:00:00 UTC, 1 January 1970 is significant largely in the context of Unix time: 00:00:00 UTC, 1 January 1970 is the Unix epoch, and Unix time is the number of seconds that have elapsed from the Unix epoch. Because Unix time is widely used in file formats and operating systems, it is necessary to have a means of converting it into other formats more legible to humans. This is the primary purpose of DATETIME\_FROM\_TIMESTAMP.
