# format-date-column

## Description

<mark style="color:purple;">`format-date-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 name`**\
Type: `text`\
Required: Yes\
The name of the column containing the date/time values.

**`original format`**\
Type: `text`\
Required: No\
The format tokens, of the original values, based on [Unicode Technical Standard #35](https://date-fns.org/v2.0.1/docs/parse). If unspecified, defaults to ISO 8601 date/time.

**`original locale`**\
Type: `text`\
Required: No\
The [language locale](https://date-fns.org/v2.0.1/docs/I18n#supported-languages) to be used when parsing the original values. If unspecified, `locale` defaults to `en-US`.

**`new format`**\
Type: `text`\
Required: No\
The format tokens, of the new values, based on [Unicode Technical Standard #35](https://date-fns.org/v2.0.1/docs/parse). If unspecified, defaults to ISO 8601 date/time.

**`new locale`**\
Type: `text`\
Required: No\
The [language locale](https://date-fns.org/v2.0.1/docs/I18n#supported-languages) to be used when formatting the new values. If unspecified, `locale` defaults to `en-US`.

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

## Outputs

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

## Examples

### Example 1: Default behaviour.

#### Inputs:

`data`:

<table><thead><tr><th width="147">id</th><th>code</th><th>name</th><th>date</th></tr></thead><tbody><tr><td>1</td><td>GB</td><td>United Kingdom</td><td>2007-01-29T00:00:00+01:00</td></tr><tr><td>2</td><td>TR</td><td>Turkey</td><td>2008-02-29T00:00:00+01:00</td></tr><tr><td>3</td><td>US</td><td>United States</td><td>2009-03-29T00:00:00+01:00</td></tr><tr><td>4</td><td>IND</td><td>India</td><td>2010-04-29T00:00:00+01:00</td></tr></tbody></table>

`original column name`: date

`original format`: *null (empty)*

`original locale`: *null (empty)*

`new format`: dd MMM yyyy

`new locale`: name

`new column name`: *null (empty)*

#### Outputs:

`data`:

| id | code | name           | date        |
| -- | ---- | -------------- | ----------- |
| 1  | GB   | United Kingdom | 28 Jan 2007 |
| 2  | TR   | Turkey         | 28 Jun 2017 |
| 3  | US   | United States  | 18 Jan 2005 |
| 4  | IND  | India          | 10 May 2012 |

-> Overwrote the `date` column with a date in `dd MMM yyyy` format

### Example 2: Date reformatted in new column.&#x20;

#### Inputs:

`data`:

<table><thead><tr><th width="147">id</th><th>code</th><th>name</th><th>date</th></tr></thead><tbody><tr><td>1</td><td>GB</td><td>United Kingdom</td><td>2007-01-29T00:00:00+01:00</td></tr><tr><td>2</td><td>TR</td><td>Turkey</td><td>2008-02-29T00:00:00+01:00</td></tr><tr><td>3</td><td>US</td><td>United States</td><td>2009-03-29T00:00:00+01:00</td></tr><tr><td>4</td><td>IND</td><td>India</td><td>2010-04-29T00:00:00+01:00</td></tr></tbody></table>

`original column name`: date

`original format`: *null (empty)*

`original locale`: *null (empty)*

`new format`: dd MMM yyyy

`new locale`: name

`new column name`: new date

#### Outputs:

`data`:

| id | code | name           | date                      | new date    |
| -- | ---- | -------------- | ------------------------- | ----------- |
| 1  | GB   | United Kingdom | 2007-01-29T00:00:00+01:00 | 28 Jan 2007 |
| 2  | TR   | Turkey         | 2017-06-29T00:00:00+01:00 | 28 Jun 2017 |
| 3  | US   | United States  | 2005-01-19T00:00:00+01:00 | 18 Jan 2005 |
| 4  | IND  | India          | 2012-05-11T00:00:00+01:00 | 10 May 2012 |

-> Created a `new date` column with the date in `dd MMM yyyy` format, derived from `date` column

## Use Cases

* Standardize date/time formats across different data sources where date/time data are stored in different formats&#x20;
* Simplify date-time into simple date
* Reformat date to align with a new target audience
* Reformat date 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-date-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.