Manage Data Source Columns

Columns API reference guide

The API endpoints on this page allow you to manage data source columns.

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

Manage data source columns

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

Create column entries

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. Columns of data sources onboarded through connections are automatically generated based on information from your data platform.

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

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 create column entries: owner, expert.
404	Data source not found.

Update data source columns

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. Columns of data sources onboarded through connections cannot be updated because they are automatically generated based on information from your data platform.

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

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

Get the columns for the specified data source

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

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 columns

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

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 data source column entries

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. Columns of data sources onboarded through connections cannot be deleted because they are automatically generated based on information from your data platform.

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

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.