Manage the Data Dictionary

Data dictionary API reference guide

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

Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.

Data dictionary workflow

1. Manage the dictionary for a data source.

2. Search dictionaries.

3. Delete a dictionary for a data source.

Manage data dictionaries

Method	Path	Purpose
POST	/dictionary/{dataSourceId}	Create the dictionary for the specified data source.
PUT	/dictionary/{dataSourceId}	Update the data dictionary for the specified data source.

Create a data dictionary

POST /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.

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

Payload example

{
  "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

{
  "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

PUT /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.

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

Payload example

{
  "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

{
  "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	/dictionary/columns	Search across all dictionary columns.

Get the dictionary for a specified data source

GET /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.

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

Response example

{
  "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

GET /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.

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

Response example

[
  "address_city",
  "address_state",
  "address_street"
]

Delete a data dictionary

DELETE /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.

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.