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

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

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

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

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

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

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

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

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

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

Delete the data dictionary for the specified data source.

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

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

```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 dictionary: 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/latest/developer-guides/api-intro/immuta-v1-api/connect-your-data/data-dictionary.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.