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

Manage data dictionaries

MethodPathPurpose

POST

/dictionary/{dataSourceId}

PUT

/dictionary/{dataSourceId}

Create a data dictionary

POST /dictionary/{dataSourceId}

Create the dictionary for the specified data source.

Query parameters

AttributeDescriptionRequired

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

AttributeDescriptionRequired

name

string The name of the column.

Yes

dataType

string The type of data in the column.

Yes

remoteType

string The type of data in the remote column.

Yes

Response parameters

AttributeDescription

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 CodeMessage

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.

Query parameters

AttributeDescriptionRequired

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

AttributeDescriptionRequired

name

string The name of the column.

Yes

dataType

string The type of data in the column.

Yes

remoteType

string The type of data in the remote column.

Yes

Response parameters

AttributeDescription

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 CodeMessage

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

MethodPathPurpose

GET

/dictionary/{dataSourceId}

GET

/dictionary/columns

Get the dictionary for a specified data source

GET /dictionary/{dataSourceId}

Get the dictionary for the specified data source.

Query parameters

AttributeDescriptionRequired

dataSourceId

integer The ID of the data source that contains the data dictionary.

Yes

Response parameters

AttributeDescription

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

AttributeDescriptionRequired

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

AttributeDescription

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.

Query parameters

AttributeDescriptionRequired

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 CodeMessage

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.

Copyright © 2014-2024 Immuta Inc. All rights reserved.