# format-time-column

## Description

<mark style="color:purple;">`format-time-column`</mark> *adaptor formats date/time values in a datatable column.*

Define the format of a date/time column and either replace the original column values or add a new column with the reformatted date-time.

## Inputs

**`data`**\
Type: `datatable`\
Required: Yes\
The datatable containing the column to be formatted.

**`original column`**\
Type: `text`\
Required: Yes\
The name of the column containing the date/time values.

**`original unit`**\
Type: `text`\
Required: No\
The unit of time measurement of the original values. If unspecified, defaults to `milliseconds`.

**`new unit`**\
Type: `text`\
Required: No\
The unit of time measurement of the new values. If unspecified, defaults to `minutes`.

**`new column`**\
Type: `text`\
Required: No\
The name of the column to which the new values will be added. If unspecified, the new values will added to the original column (specified by `original column`), overwriting the original values.

## Outputs

**`data`**\
Type: `datatable`\
A datatable with formatted values.

## Examples

### Example 1: Default behaviour.

#### Inputs:

`data`:

| id | time |
| -- | ---- |
| 1  | 1    |
| 2  | 4    |
| 3  | 5    |
| 4  | 2    |

`original column`: time

`original unit`: hours

`new unit`: minutes

`new column` : *null (empty)*

#### Outputs:

`data`:

| id | time |
| -- | ---- |
| 1  | 60   |
| 2  | 240  |
| 3  | 300  |
| 4  | 120  |

-> Overwrote the data in the `time` column with the time in `minutes`instead of `hours`

### Example 2: Time reformatted in new column.

#### Inputs:

`data`:

| id | time (hours) |
| -- | ------------ |
| 1  | 1            |
| 2  | 4            |
| 3  | 5            |
| 4  | 2            |

`original column`: time (hours)

`original unit`: hours

`new unit`: seconds

`new column` : time (seconds)

#### Outputs:

`data`:

| id | time (hours) | time (seconds) |
| -- | ------------ | -------------- |
| 1  | 1            | 3600           |
| 2  | 4            | 14400          |
| 3  | 5            | 18000          |
| 4  | 2            | 7200           |

-> Created a `time (seconds)` column with the time in `seconds`, derived from `time (hours)` column.

## Use Cases

* Standardize temporal data elements across different data sources where temportal data are stored in different formats&#x20;
* Simplify temporal data formats
* Reformat temporal data elements to a format more useful for visualisation&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cgps.gitbook.io/data-flo/reference-guide/format-time-column.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.