# Manage the Data Dictionary

The data dictionary API allows you to manage the data dictionary for your data sources.

{% 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 %}

## Data dictionary workflow

1. [Manage the dictionary for a data source](#manage-data-dictionaries).
2. [Search dictionaries](#search-data-dictionaries).
3. [Delete a dictionary for a data source](#delete-a-data-dictionary).

## Manage data dictionaries

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

### Create a data dictionary

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

Create the dictionary for the specified data source.

#### Query parameters

| Attribute    | Description                                                                                         | Required |
| ------------ | --------------------------------------------------------------------------------------------------- | -------- |
| dataSourceId | `integer` The ID of the data source that will contain the data dictionary.                          | **Yes**  |
| body         | `array[object]` Data dictionary metadata, including column names, data types, description and tags. | **Yes**  |

#### Payload parameters

| Attribute               | Description                                                 | Required |
| ----------------------- | ----------------------------------------------------------- | -------- |
| **metadata**            | `array[string]` Metadata for each column in the dictionary. | **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 dictionary is associated with.                                                              |
| id         | `integer` The ID of the dictionary object.                                                                                          |
| metadata   | `array[string]` Metadata for the individual fields in the dictionary, including `name`, `dataType`, and `remoteType`.               |
| types      | `array[string]` A list of all data types the dictionary contains, such as `text`, `integer`, `json`, or `timestamp with time zone`. |

#### Request example

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

```shell
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 delete dictionary: owner,expert. |
| 404         | Data source not found.                                                        |

### Update a data dictionary

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

Update the dictionary for the specified data source.

#### Query parameters

| Attribute    | Description                                                                                         | Required |
| ------------ | --------------------------------------------------------------------------------------------------- | -------- |
| dataSourceId | `integer` The ID of the data source that will contain the data dictionary.                          | **Yes**  |
| body         | `array[object]` Data dictionary metadata, including column names, data types, description and tags. | **Yes**  |

#### Payload parameters

| Attribute               | Description                                                 | Required |
| ----------------------- | ----------------------------------------------------------- | -------- |
| **metadata**            | `array[string]` Metadata for each column in the dictionary. | **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 dictionary is associated with.                                                              |
| id         | `integer` The ID of the dictionary object.                                                                                          |
| metadata   | `array[string]` Metadata for the individual fields in the dictionary, including `name`, `dataType`, and `remoteType`.               |
| types      | `array[string]` A list of all data types the dictionary contains, such as `text`, `integer`, `json`, or `timestamp with time zone`. |

#### Request example

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

```shell
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 delete dictionary: owner,expert. |
| 404         | Data source not found.                                                        |

## Search data dictionaries

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

### Get the dictionary for a specified data source

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

Get the dictionary for the specified data source.

#### Query parameters

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

#### Response parameters

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

#### Request example

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

```shell
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 dictionary columns

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

Search across all dictionary 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 parameters

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

#### Request example

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

```shell
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 a data dictionary

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

Delete the data dictionary for the specified data source.

#### Query parameters

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

### Request example

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

```shell
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 dictionary: owner,expert. |
| 404         | Data source not found.                                                        |