# 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](/saas/configuration/integrations/data-and-integrations/registering-metadata.md). 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](/saas/configuration/integrations/data-and-integrations/registering-metadata.md). 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](/saas/configuration/integrations/data-and-integrations/registering-metadata.md). 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.                                                             |


---

# 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://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/connect-your-data/manage-data-source-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.