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