Data Source Browsing

Description:

The API below allows you to get an object's logical and physical metadata from Alation catalog. The objects could be any of the following:

1. Data source
2. Schema
3. Table
4. Column

Metadata Explanation

The logical metadata for an object includes:

Title : The title given to an object
Description : The description given to an object
Custom Fields : Custom Fields added to an object. For Example: Steward, Last Updated etc.

The physical metadata for an object includes:

Object name : Name of the object
Data type : Data type of a column
Whether the object is a view

NOTE: Object could be any of the following:
1. Data Source
2. Schema
3. Table
4. Column

Get Metadata for an Object

This API lets you get logical and physical metadata of an object.

This is a read-only API. Physical metadata such as names and types can only be modified on virtual data sources (see Virtual Data Source). Regular data sources are synced automatically, so the physical metadata is not editable. Logical metadata can be uploaded in bulk (see Upload Logical Metadata ).

URL

GET /catalog/**<otype>**/?**<params>**

Replace with one of the following:

datasource
schema
table
column

Replace with your list of parameters. Multiple parameters can be combined as PARAM1&PARAM2

URL Parameters

Name	Description	Applies to
id	Unique identifier of an object Example: /catalog/datasource/?id=1	All objects
title	Title given to the object Example: /catalog/datasource/?title=Employee	All objects
name	Name of the object Example: /catalog/datasource/?name=employee_table NOTE: This parameter value needs to be all lowercase	Schema Table Column
ds_id	Unique identifier of the data source the objects belong to Example: /catalog/schema/?ds_id=1	Schema Table column
schema_id	Unique identifier of the schema the objects belong to Example: /catalog/table/?schema_id=1	Table Column
schema_name	Name of the schema the objects belong to Example: /catalog/table/?schema_name=emp_schema	Table
data_type	The data type of a column Example: /catalog/column/?data_type=number	Column
nullable	The value for this field tells whether a column supports null value Example: /catalog/column/?nullable=false NOTE: This parameter supports only two values: true false	Column
table_id	Unique identifier of the table, the objects belong to Example: /catalog/column/?table_id=1	Column
table_name	Name of the table(<schema_name>.<table_name>) the objects belong to Example: /catalog/column/?table_name=emp_schema.emp_table	Column
limit	Limit the number of objects returned Example: /catalog/datasource/?limit=10	All objects
custom_fields	Specifies the custom fields that belong to an object Example: /catalog/datasource/?custom_fields=[{"field_name":"Season","value_type":"text","value":"Spring"}]	All objects

NOTE: None of the above parameters are required to place a GET request for the API.

Headers

HTTP Header	Value
TOKEN	<your_token>

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

Success Response

Content-Type: application/json

Status: 200 OK

Body

[
    {
        "custom_fields": [
            {
                "value": "Spring",
                "value_type": "text",
                "field_name": "Season"
            }
        ],
        "description": "This is schema for climate",
        "ds_id": 1,
        "db_comment": null,
        "id": 1,
        "name": "schema_climate",
        "title": "Climate Schema",
        "url": "/schema/1/"
    }
]

NOTE: This is a sample response for /catalog/schema/?id=1 API call.

Error Response

Invalid Token

Status: 403 Forbidden

Body

{
   "detail": "Authentication failed"
}

Missing Token Header

Status: 403 Forbidden

Body

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

Alternative URLs

Get schemas in a data source:

GET [/catalog/datasource/**<datasource_id>**/schema/?**<params>](/metadata_api/get_schemas_in_a_data_source/index.html)

Get tables in a schema:

GET /catalog/datasource/**<datasource_id>**/schema/**<schema_key>**/table/?**<params>**

Get columns in a table:

GET /catalog/datasource/**<datasource_id>**/schema/**<schema_key>**/table/**<table_key>**/column/?**<params>**

NOTE: The above alternative APIs are available in version 3.4 or later

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/catalog"

# Get logical and physical metadata of all data sources in alation catalog
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/datasource/"

# Get logical and physical metadata of all schemas in alation catalog
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/schema/"

# Get logical and physical metadata of all tables in alation catalog
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/table/"

# Get logical and physical metadata of all columns in alation catalog
curl -H "TOKEN: ${API_TOKEN}" "${BASE_URL}/column/"

Python

# This example prints only id and title of a data source, to know all the parameters in a response, please refer to the sample responses below
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/catalog/'

# Get logical and physical metedata of all data sources in alation catalog
response = requests.get(BASE_URL + 'datasource/', headers=headers)
datasources = json.loads(response.text)
for datasource in datasources:
    print ("ID: %s, Title: %s" % (datasource['id'], datasource['title']))

# Get logical and physical metadata of all schemas in alation catalog
response = requests.get(BASE_URL + 'schema/', headers=headers)
schemas = json.loads(response.text)
for schema in schemas:
    print ("ID: %s, Title: %s" % (schema['id'], schema['title']))

# Get logical and physical metadata of all tables in alation catalog
response = requests.get(BASE_URL + 'table/', headers=headers)
tables = json.loads(response.text)
for table in tables:
    print ("ID: %s, Title: %s" % (table['id'], table['title']))

# Get logical and physical metadata of all columns in alation catalog
response = requests.get(BASE_URL + 'column/', headers=headers)
columns = json.loads(response.text)
for column in columns:
    print ("ID: %s, Title: %s" % (column['id'], column['title']))

Sample Request and Response

URL

Get a data source which has unique identifier as 1

GET /catalog/datasource/?id=1

Sample Success Response

Body

[
    {
        "custom_fields": [
            {
                "value": "[email protected]",
                "value_type": "user",
                "field_name": "Steward"
            }
        ],
        "dbtype": "oracle",
        "description": "This is oracle data source",
        "id": 1,
        "is_virtual": false,
        "title": "oracle-db",
        "uri": "oracle:thin:@//o11-170.ck1trs11.us-east-1.rds.amazonaws.com:1521/company",
        "url": "/data/1/"
    }
]

URL

Get all schemas whose title is set to employee schema

GET /catalog/schema/?title=employee schema

Sample Success Response

Body

[
    {
        "custom_fields": [
            {
                "value": "[email protected]",
                "value_type": "user",
                "field_name": "Steward"
            }
        ],
        "description": "This is a schema",
        "ds_id": 1,
        "db_comment": null,
        "id": 1,
        "name": "EMP_SCHEMA",
        "title": "employee schema",
        "url": "/schema/1/"
    }
]

URL

Get all tables in schemas with name emp_schema

GET /catalog/table/?schema_name=emp_schema

Sample Success Response

Body

[
    {
        "custom_fields": [
        	{
                "value": "[email protected]",
                "value_type": "user",
                "field_name": "Steward"
            }
        ],
        "description": "<p>this is employee details table</p>",
        "ds_id": 1,
        "id": 1,
        "is_view": false,
        "name": "EMPLOYEE",
        "schema_id": 1,
        "schema_name": "emp_schema",
        "title": "Employee",
        "url": "/table/1/",
        "synonyms": {
          "table_name": "public_emp_schema",
          "schema_name": "public"
        },
        "base_table": null,
        "synonyms": null,
        "db_comment": null
    },
    {
        "custom_fields": [],
        "description": "",
        "ds_id": 1,
        "id": 2,
        "is_view": false,
        "name": "EMP_SALARY",
        "schema_id": 1,
        "schema_name": "emp_schema",
        "title": "",
        "url": "/table/2/",
        "synonyms": null,
        "base_table": {
          "table_name": "emp_table",
          "schema_name": "emp_schema"
        },
        "db_comment": null
    }
]

NOTE: The <p>..</p> is appended to the description because the description is a paragraph. As the description can have links, images or paragraphs, we return it as html.

URL

Get all columns in a table whose unique identifier is 1

GET /catalog/column/?table_id=1

Sample Success Response

Body

[
    {
        "custom_fields": [],
        "data_type": "number(10)",
        "description": "employee id",
        "ds_id": 1,
        "db_comment": null,
        "id": 1,
        "is_primary_key": true,
        "is_foreign_key": false,
        "name": "emp_id",
        "nullable": false,
        "schema_id": 1,
        "table_id": 1,
        "table_name": "emp_schema.EMPLOYEE",
        "title": "Employee ID",
        "position": 2,
        "url": "/attribute/1/"
    },
    {
        "custom_fields": [],
        "data_type": "varchar2(100)",
        "description": "",
        "ds_id": 1,
        "db_comment": null,
        "id": 2,
        "is_primary_key": false,
        "is_foreign_key": false,
        "name": "first_name",
        "nullable": true,
        "schema_id": 1,
        "table_id": 1,
        "table_name": "emp_schema.EMPLOYEE",
        "title": "First Name",
        "position": 1,
        "url": "/attribute/2/"
    }
]