# map-column-values

## Description

<mark style="color:purple;">`map-column-values`</mark> *adaptor adds a new column to a datatable by mapping values of an existing column.*

## Inputs

**`data`**\
Type: `datatable`\
Required: Yes\
The columns and rows.

**`original column`**\
Type: `text`\
Required: Yes\
The name of an existing column containing values to be mapped.

**`values`**\
Type: `dictionary`\
Required: Yes\
The map of existing and new values, where the keys are the existing values in the original column, and the values are the corresponding values to be written to the new column.

**`new column`**\
Type: `text`\
Required: No\
The name of the new column to which the mapped values will be written. If unspecified, mapped values will be written to the original column.

**`case sensitive`**\
Type: `boolean`\
Required: No\
Whether lowercase and uppercase letters should be treated as equivalent. If unspecified, defaults to `False` (lowercase and uppercase letters are treated as equivalent).

**`unmapped values`**\
Type: `text`\
Required: No\
Specifies what values to write in the new column when the original column values are not included as map keys. If unspecified, defaults to `Replace original value with blank`.

## Outputs

**`data`**\
Type: `datatable`\
A datatable containing mapped values in `new column`.

## Examples

### Example 1: Default behaviour.

Inputs:

`data`:

| id | code | name           |
| -- | ---- | -------------- |
| 1  | GB   | United Kingdom |
| 2  | TR   | Turkey         |
| 3  | US   | United States  |
| 4  | IN   | India          |

`original column`: code

`values:`

<table><thead><tr><th>Key</th><th>Value</th><th data-hidden></th></tr></thead><tbody><tr><td>GB</td><td>gb</td><td></td></tr><tr><td>TR</td><td>tr</td><td></td></tr><tr><td>US</td><td>us</td><td></td></tr><tr><td>IN</td><td>in</td><td></td></tr></tbody></table>

`new column:`*null (empty)*\
\
`case sensitive:`*null (empty)*\
\
`unmapped values:` *null (empty)*

#### Outputs:

`data`:

<table><thead><tr><th width="259">id</th><th>code</th><th>name</th></tr></thead><tbody><tr><td>1</td><td>gb</td><td>United Kingdom</td></tr><tr><td>2</td><td>tr</td><td>Turkey</td></tr><tr><td>3</td><td>us</td><td>United States</td></tr><tr><td>4</td><td>in</td><td>India</td></tr></tbody></table>

-> Mapped values in the `code` column, replacing existing values.

### Example 2: Specify new column and unmapped values.

Inputs:

`data`:

| id | code | name           |
| -- | ---- | -------------- |
| 1  | GB   | United Kingdom |
| 2  | TR   | Turkey         |
| 3  | US   | United States  |
| 4  | IN   | India          |

`original column`: code

`values:`

<table><thead><tr><th>Key</th><th>Value</th><th data-hidden></th></tr></thead><tbody><tr><td>GB</td><td>gb</td><td></td></tr><tr><td>TR</td><td>tr</td><td></td></tr><tr><td>US</td><td>us</td><td></td></tr></tbody></table>

`new column:` country code\
\
`case sensitive:`*null (empty)*\
\
`unmapped values:` none

#### Outputs:

`data`:

<table><thead><tr><th width="179">id</th><th>code</th><th>name</th><th>country code</th></tr></thead><tbody><tr><td>1</td><td>GB</td><td>United Kingdom</td><td>gb</td></tr><tr><td>2</td><td>TR</td><td>Turkey</td><td>tr</td></tr><tr><td>3</td><td>US</td><td>United States</td><td>us</td></tr><tr><td>4</td><td>IN</td><td>India</td><td>none</td></tr></tbody></table>

-> Mapped values in the `code` column, creating a new column named `country code`. Unmapped value was set to `none.`


---

# 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/map-column-values.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.