> For the complete documentation index, see [llms.txt](https://cgps.gitbook.io/data-flo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cgps.gitbook.io/data-flo/reference-guide/rename-columns.md).

# rename-columns

## Description

<mark style="color:purple;">`rename-columns`</mark> *adaptor renames existing columns in a datatable.*

Maps old (existing) column names to new column names, with the option to discard columns that are not listed in the mapping.

Note that this does not create a second copy of mapped columns with a new name, it simply changes the name of the mapped column.

## Inputs

**`data`**\
Type: `datatable`\
Required: Yes\
The datatable containing columns to be renamed.

**`column names`**\
Type: `dictionary`\
Required: Yes\
The mapping of old column names to new ones.

**`discard unmapped`**\
Type: `boolean`\
Required: No\
Specifies whether to discard columns which are not mapped in `column names`. If unspecified, defaults to `False` (unmapped columns are kept).

## Outputs

**`data`**\
Type: `datatable`\
A datatable with the columns renamed.

## Examples

### Example 1: Default behaviour.

#### Inputs:

`data:`

| id | code | name           |
| -- | ---- | -------------- |
| 1  | GB   | United Kingdom |
| 2  | TR   | Turkey         |
| 3  | US   | United States  |
| 4  | IND  | India          |
| 5  | IND  | India          |
| 6  | us   | United States  |

`column names:`

| KEY  | VALUE        |
| ---- | ------------ |
| code | country code |
| name | country name |

`discard unmapped:` *null (empty)*

#### Outputs:

`data`:

| id | country code | country name   |
| -- | ------------ | -------------- |
| 1  | GB           | United Kingdom |
| 2  | TR           | Turkey         |
| 3  | US           | United States  |
| 4  | IND          | India          |
| 5  | IND          | India          |
| 6  | us           | United States  |

-> Renamed the columns `code` and `name` to `country code` and `country name` respectively.

### Example 2: Discard unmapped columns.

#### Inputs:

`data:`

| id | code | name           |
| -- | ---- | -------------- |
| 1  | GB   | United Kingdom |
| 2  | TR   | Turkey         |
| 3  | US   | United States  |
| 4  | IND  | India          |
| 5  | IND  | India          |
| 6  | us   | United States  |

`column names:`

| KEY  | VALUE        |
| ---- | ------------ |
| code | country code |
| name | country name |

`discard unmapped:` True

#### Outputs:

`data`:

| country code | country name   |
| ------------ | -------------- |
| GB           | United Kingdom |
| TR           | Turkey         |
| US           | United States  |
| IND          | India          |
| IND          | India          |
| us           | United States  |

-> Renamed the mapped columns and discared the unmapped column `id`.

## Use Cases

* Preparing datatables for merging by ensuring that the same name is used for the same column in both datasets.
* Creating user-friendly column display names before exporting data to a Microreact project or an external report.
* Making column names more descriptive to ensure proper interpretation.