# Manage Data Source Columns

The API endpoints on this page allow you to manage data source columns.

{% hint style="info" %}
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
{% endhint %}

## Manage data source columns

| Method | Path                         | Purpose                                                                         |
| ------ | ---------------------------- | ------------------------------------------------------------------------------- |
| POST   | `/dictionary/{dataSourceId}` | [Create column entries for the specified data source](#create-column-entries).  |
| PUT    | `/dictionary/{dataSourceId}` | [Update the columns of the specified data source](#update-data-source-columns). |

### Create column entries

{% hint style="warning" %}
**Deprecation notice**

Support for this endpoint has been deprecated and is only available if your data sources were onboarded using a legacy [data registration method](https://documentation.immuta.com/saas/configuration/integrations/data-and-integrations/registering-metadata). Columns of data sources onboarded through connections are automatically generated based on information from your data platform.
{% endhint %}

<mark style="color:green;">`POST`</mark> `/dictionary/{dataSourceId}`

Create column entries for the specified data source.

**Required**: The global `GOVERNANCE` permission or be the data source owner

#### Request parameter

| Attribute    | Description                                                    | Required |
| ------------ | -------------------------------------------------------------- | -------- |
| dataSourceId | `integer` The ID of the data source that contains the columns. | **Yes**  |

#### Payload parameters

| Attribute               | Description                                     | Required |
| ----------------------- | ----------------------------------------------- | -------- |
| **metadata**            | `array[string]` Metadata for each column.       | **Yes**  |
| metadata.**name**       | `string` The name of the column.                | **Yes**  |
| metadata.**dataType**   | `string` The type of data in the column.        | **Yes**  |
| metadata.**remoteType** | `string` The type of data in the remote column. | **Yes**  |

#### Response parameters

| Attribute  | Description                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
| createdAt  | `timestamp` When the object was created.                                                                                        |
| dataSource | `integer` The ID of the data source the columns are associated with.                                                            |
| id         | `integer` The ID of the columns object.                                                                                         |
| metadata   | `array[string]` Column metadata, including `name`, `dataType`, and `remoteType`.                                                |
| types      | `array[string]` A list of all data types the columns contain, such as `text`, `integer`, `json`, or `timestamp with time zone`. |

#### Request example

The following request creates column entries (saved in `example-payload.json`) for the data source with ID `1`.

```bash
curl \
    --request POST \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --header "Content-Type: application/json" \
    --data @example-payload.json \
    https://demo.immuta.com/dictionary/1
```

**Payload example**

```json
{
  "metadata": [
    {
      "name": "notificationType",
      "dataType": "text",
      "remoteType": "text"
    },
    {
      "name": "actionBy",
      "dataType": "text",
      "remoteType": "integer"
    },
    {
      "name": "targetUser",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "metadata",
      "dataType": "json",
      "remoteType": "json"
    },
    {
      "name": "id",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "notifyInitiator",
      "dataType": "text",
      "remoteType": "boolean"
    },
    {
      "name": "eventTime",
      "dataType": "timestamp with time zone",
      "remoteType": "timestamp with time zone"
    }
  ]
}
```

#### Response example

```json
{
  "createdAt": "2018-03-21T10:52:30.535Z",
  "dataSource": 1,
  "id": 1,
  "metadata": [
    {
      "name": "notificationType",
      "dataType": "text",
      "remoteType": "text"
    },
    {
      "name": "actionBy",
      "dataType": "text",
      "remoteType": "integer"
    },
    {
      "name": "targetUser",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "metadata",
      "dataType": "json",
      "remoteType": "json"
    },
    {
      "name": "id",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "notifyInitiator",
      "dataType": "text",
      "remoteType": "boolean"
    },
    {
      "name": "eventTime",
      "dataType": "timestamp with time zone",
      "remoteType": "timestamp with time zone"
    }
  ],
  "types": [
    "text",
    "integer",
    "json",
    "timestamp with time zone"
  ],
  "updatedAt": "2018-03-21T12:18:25.531Z"
}
```

Other status codes returned include:

| Status Code | Message                                                                            |
| ----------- | ---------------------------------------------------------------------------------- |
| 400         | Bad request: (detailed reason).                                                    |
| 401         | A valid Authorization token must be provided.                                      |
| 403         | User must have one of the following roles to create column entries: owner, expert. |
| 404         | Data source not found.                                                             |

### Update data source columns

{% hint style="warning" %}
**Deprecation notice**

Support for this endpoint has been deprecated and is only available if your data sources were onboarded using a legacy [data registration method](https://documentation.immuta.com/saas/configuration/integrations/data-and-integrations/registering-metadata). Columns of data sources onboarded through connections cannot be updated because they are automatically generated based on information from your data platform.
{% endhint %}

<mark style="color:green;">`PUT`</mark> `/dictionary/{dataSourceId}`

Update columns for the specified data source.

**Required**: The global `GOVERNANCE` permission or be the data source owner or expert

#### Request parameter

| Attribute    | Description                                                        | Required |
| ------------ | ------------------------------------------------------------------ | -------- |
| dataSourceId | `integer` The ID of the data source that will contain the columns. | **Yes**  |

#### Payload parameters

| Attribute               | Description                                     | Required |
| ----------------------- | ----------------------------------------------- | -------- |
| **metadata**            | `array[string]` Metadata for each column.       | **Yes**  |
| metadata.**name**       | `string` The name of the column.                | **Yes**  |
| metadata.**dataType**   | `string` The type of data in the column.        | **Yes**  |
| metadata.**remoteType** | `string` The type of data in the remote column. | **Yes**  |

#### Response parameters

| Attribute  | Description                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
| createdAt  | `timestamp` When the object was created.                                                                                        |
| dataSource | `integer` The ID of the data source the columns are associated with.                                                            |
| id         | `integer` The ID of the columns object.                                                                                         |
| metadata   | `array[string]` Metadata for the columns, including `name`, `dataType`, and `remoteType`.                                       |
| types      | `array[string]` A list of all data types the columns contain, such as `text`, `integer`, `json`, or `timestamp with time zone`. |

#### Request example

The request below updates columns for the data source with the ID `1`.

```bash
curl \
    --request PUT \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --header "Content-Type: application/json" \
    --data @example-payload.json \
    https://demo.immuta.com/dictionary/1
```

**Payload example**

```json
{
  "metadata": [
    {
      "name": "notificationType",
      "dataType": "text",
      "remoteType": "text"
    },
    {
      "name": "actionBy",
      "dataType": "text",
      "remoteType": "integer"
    },
    {
      "name": "targetUser",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "metadata",
      "dataType": "json",
      "remoteType": "json"
    },
    {
      "name": "id",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "notifyInitiator",
      "dataType": "text",
      "remoteType": "boolean"
    },
    {
      "name": "eventTime",
      "dataType": "timestamp with time zone",
      "remoteType": "timestamp with time zone"
    }
  ]
}
```

#### Response example

```json
{
  "createdAt": "2018-03-21T10:52:30.535Z",
  "dataSource": 1,
  "id": 1,
  "metadata": [
    {
      "name": "notificationType",
      "dataType": "text",
      "remoteType": "text"
    },
    {
      "name": "actionBy",
      "dataType": "text",
      "remoteType": "integer"
    },
    {
      "name": "targetUser",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "metadata",
      "dataType": "json",
      "remoteType": "json"
    },
    {
      "name": "id",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "notifyInitiator",
      "dataType": "text",
      "remoteType": "boolean"
    },
    {
      "name": "eventTime",
      "dataType": "timestamp with time zone",
      "remoteType": "timestamp with time zone"
    }
  ],
  "types": [
    "text",
    "integer",
    "json",
    "timestamp with time zone"
  ],
  "updatedAt": "2018-03-21T12:18:25.531Z"
}
```

Other status codes returned include

| Status Code | Message                                                                            |
| ----------- | ---------------------------------------------------------------------------------- |
| 400         | Bad request: (detailed reason).                                                    |
| 401         | A valid Authorization token must be provided.                                      |
| 403         | User must have one of the following roles to update column entries: owner, expert. |
| 404         | Data source not found.                                                             |

## Search columns

| Method | Path                         | Purpose                                                                                          |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------------------ |
| GET    | `/dictionary/{dataSourceId}` | [Get the columns for the specified data source](#get-the-columns-for-the-specified-data-source). |
| GET    | `/dictionary/columns`        | [Search across all columns](#search-columns).                                                    |

### Get the columns for the specified data source

<mark style="color:green;">`GET`</mark> `/dictionary/{dataSourceId}`

Get the columns for the specified data source.

#### Request parameter

| Attribute    | Description                                                    | Required |
| ------------ | -------------------------------------------------------------- | -------- |
| dataSourceId | `integer` The ID of the data source that contains the columns. | **Yes**  |

#### Response parameters

| Attribute  | Description                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
| createdAt  | `timestamp` When the object was created.                                                                                        |
| dataSource | `integer` The ID of the data source the columns are associated with.                                                            |
| id         | `integer` The ID of the columns object.                                                                                         |
| metadata   | `array[string]` Metadata for the columns, including `name`, `dataType`, and `remoteType`.                                       |
| types      | `array[string]` A list of all data types the columns contain, such as `text`, `integer`, `json`, or `timestamp with time zone`. |

#### Request example

The request below gets the columns for the data source with the ID `1`.

```bash
curl \
    --request GET \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --header "Content-Type: application/json" \
    https://demo.immuta.com/dictionary/1
```

#### Response example

```json
{
  "createdAt": "2018-03-21T10:52:30.535Z",
  "dataSource": 1,
  "id": 1,
  "metadata": [
    {
      "name": "notificationType",
      "dataType": "text",
      "remoteType": "text"
    },
    {
      "name": "actionBy",
      "dataType": "text",
      "remoteType": "integer"
    },
    {
      "name": "targetUser",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "metadata",
      "dataType": "json",
      "remoteType": "json"
    },
    {
      "name": "id",
      "dataType": "integer",
      "remoteType": "integer"
    },
    {
      "name": "notifyInitiator",
      "dataType": "text",
      "remoteType": "boolean"
    },
    {
      "name": "eventTime",
      "dataType": "timestamp with time zone",
      "remoteType": "timestamp with time zone"
    }
  ],
  "types": [
    "text",
    "integer",
    "json",
    "timestamp with time zone"
  ],
  "updatedAt": "2018-03-21T12:18:25.531Z"
}
```

### Search across all columns

<mark style="color:green;">`GET`</mark> `/dictionary/columns`

Search across all columns.

#### Query parameters

| Attribute  | Description                                                                                                 | Required |
| ---------- | ----------------------------------------------------------------------------------------------------------- | -------- |
| searchText | `string` A string used to filter returned columns. The query is executed with a wildcard prefix and suffix. | No       |
| limit      | `integer` The maximum number of search results that will be returned. **Default is `10`**.                  | No       |

#### Response parameter

| Attribute  | Description                      |
| ---------- | -------------------------------- |
| columnName | `string` The name of the column. |

#### Request example

The following request searches for columns in all data sources that contain the text `address` in their name, with a limit of `10` results.

```bash
curl \
    --request GET \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --header "Content-Type: application/json" \
    https://demo.immuta.com/dictionary/columns?searchText=address&limit=10
```

#### Response example

```json
[
  "address_city",
  "address_state",
  "address_street"
]
```

## Delete data source column entries

{% hint style="warning" %}
**Deprecation notice**

Support for this endpoint has been deprecated and is only available if your data sources were onboarded using a legacy [data registration method](https://documentation.immuta.com/saas/configuration/integrations/data-and-integrations/registering-metadata). Columns of data sources onboarded through connections cannot be deleted because they are automatically generated based on information from your data platform.
{% endhint %}

<mark style="color:green;">`DELETE`</mark> `/dictionary/{dataSourceId}`

Delete the column entries for the specified data source.

**Required**: The global `GOVERNANCE` permission or be the data source owner

#### Request parameter

| Attribute    | Description                          | Required |
| ------------ | ------------------------------------ | -------- |
| dataSourceId | `integer` The ID of the data source. | **Yes**  |

### Request example

The request below deletes column entries for the data source with ID `1`.

```bash
curl \
    --request DELETE \
    --header "Authorization: Bearer dea464c07bd07300095caa8" \
    --header "Content-Type: application/json" \
    https://demo.immuta.com/dictionary/1
```

### Response example

This endpoint returns `{}` on success.

Other status codes returned include

| Status Code | Message                                                                            |
| ----------- | ---------------------------------------------------------------------------------- |
| 401         | A valid Authorization token must be provided.                                      |
| 403         | User must have one of the following roles to delete column entries: owner, expert. |
| 404         | Data source not found.                                                             |