# 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.


---

# 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/rename-columns.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.