HomeGuidesRecipesAPI ReferencePython SDK
Alation Help Center
API Reference

Find Objects by Custom Field

Find Objects by Custom Field

Description

This API allows you to find objects in the catalog by their custom fields.

Note:

  1. Custom fields applied from catalog sets are not included in the API response.
  2. In this API, the word 'attribute' refers to a column in a database table.
  3. After release 5.7 and above, this API returns only non-deleted objects, by default. Use include_deleted to fetch all the objects.

URL

GET /api/v1/bulk_metadata/data_dictionary/**<otype>**?custom_fields=**<fields_json>**

Path Parameters

NameRequiredDescription
otypeYesThe type of object whose custom field metadata is to be retrieved.
otype can be one of the following:
schema
table
attribute

URL Parameters

NameRequiredDescription
custom_fieldsYesCustom fields whose information is to be retrieved. The general format of the request is /api/v1/bulk_metadata/data_dictionary/<otype>?custom_fields={"<custom_field_name>":[<filters>]}
where <filters> is the list of custom field values to filter the result from or an empty list to return all NON-null values and <custom_field_name> is the singular name of a custom field

For Example: Return all tables that have custom field Steward(with non-null value) and a custom field is_used whose value is set to 'yes'
/api/v1/bulk_metadata/data_dictionary/table?custom_fields={"Steward":[],"is_used":["yes"]}
include_deletedNoBoolean parameter indicating whether to include deleted objects or not.
Default value is False. Accepted values are True and False.

Headers

HTTP HeaderValue
TOKEN<your_token>

Replace <your_token> with API Token which can be obtained from getToken API call (Get API Token).

Success Response

Content-Type: text/html

Status: 200 OK

Body

{"key": "1.emp_schema.employee", "Steward": "[email protected]:user", "is_used": "yes"}
{"key": "1.emp_schema.salary", "Steward": "[email protected]:user"}

NOTE: The response returned is a list of objects and custom fields separated by a newline. Each row in the response is a separate JSON object.The key in response represents the object the custom fields belong to. The value for keys could be in one of the following formats:

ObjectValue Format
Schema<datasource_id>.<schema_name>
Table<datasource_id>.<schema_name>.<table_name>
Attribute<datasource_id>.<schema_name>.<table_name>.<attribute_name>

NOTE: In above response, each row is a separate JSON object. If you try to parse the entire response body using a JSON reader/parser it fails, as any JSON reader/parser expects the whole body to be either a single JSON object or a JSON array.

To know the format of custom field values returned, please refer custom field value format

Error Response

Invalid Token

Status: 401 UNAUTHORIZED

Body

{
   "detail": "Authentication failed"
}

Missing Token Header

Status: 401 UNAUTHORIZED

Body

{
    "detail": "Authentication credentials were not provided."
}

Code Samples

cURL

#!/bin/bash

# This is an example token. Please replace this with your token.
API_TOKEN="2abcd-4c04-4c21-8692-eda27a877f90"

BASE_URL="https://alation.yourcompany.com/api/v1/bulk_metadata/data_dictionary"

# Get all schemas which have Steward as their custom field
# This request returns schemas which have non-null stewards
curl -H "TOKEN: ${API_TOKEN}" -g "${BASE_URL}/schema?custom_fields={\"Steward\":[]}"

# Get all tables which have [email protected] and [email protected] as their Stewards
# Note that the 'user' type is appended to the email addresses since the stewards are users
curl -H "TOKEN: ${API_TOKEN}" -g "${BASE_URL}/table?custom_fields={\"Steward\":[\"[email protected]:user\",\"[email protected]:user\"]}"

Python

import requests
import json

# This is an example token. Please replace this with your token.
headers = {'Token': '2abcd-4c04-4c21-8692-eda27a877f90'}
BASE_URL = 'https://alation.yourcompany.com/api/v1/bulk_metadata/data_dictionary/'

# Get all attributes which have Stewards
response = requests.get(BASE_URL + 'attribute?custom_fields={"Steward":[]}', headers=headers)
# Split the response by newline to parse each json object separately
attributes = response.text.split("\n")

for attribute in attributes:
    # To skip the last newline character after the results
    if attribute != '':
        result = json.loads(attribute)
        print "Key: %s" % (result['key'])

Sample Request and Response

URL

Get all attributes with Stewards

GET /api/v1/bulk_metadata/data_dictionary/attribute?custom_fields={"Steward":[]}

Success Response

Body

{"key": "1.emp_schema.employee.emp_id", "Steward": "[email protected]:user"}
{"key": "1.emp_schema.employee.first_name", "Steward": "[email protected]:user"}

URL

Get all tables with custom fields 'Steward' and 'is_used'

GET /api/v1/bulk_metadata/data_dictionary/table?custom_fields={"Steward":[],"is_used":[]}

Success Response

Body

{"key": "1.emp_schema.employee", "Steward": "[email protected]:user;[email protected]:user", "is_used": "yes"}
{"key": "1.emp_schema.salary", "Steward": "[email protected]:user"}