HomeGuidesRecipesAPI ReferencePython SDK
Alation Help Center
API Reference

Relational Get APIs

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:

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

The physical metadata for an object includes:

  1. Object name : Name of the object
  2. Data type : Data type of a column
  3. 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 <otype> with one of the following:

datasource
schema
table
column

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

URL Parameters

NameDescriptionApplies to
idUnique identifier of an object
Example: /catalog/datasource/?id=1
All objects
titleTitle given to the object
Example: /catalog/datasource/?title=Employee
All objects
nameName of the object
Example: /catalog/datasource/?name=employee_table
NOTE: This parameter value needs to be all lowercase
Schema
Table
Column
ds_idUnique identifier of the data source the objects belong to
Example: /catalog/schema/?ds_id=1
Schema
Table
column
schema_idUnique identifier of the schema the objects belong to
Example: /catalog/table/?schema_id=1
Table
Column
schema_nameName of the schema the objects belong to
Example: /catalog/table/?schema_name=emp_schema
Table
data_typeThe data type of a column
Example: /catalog/column/?data_type=number
Column
nullableThe 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_idUnique identifier of the table, the objects belong to
Example: /catalog/column/?table_id=1
Column
table_nameName of the table(<schema_name>.<table_name>) the objects belong to
Example: /catalog/column/?table_name=emp_schema.emp_table
Column
limitLimit the number of objects returned
Example: /catalog/datasource/?limit=10
All objects
custom_fieldsSpecifies 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 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: 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/"
    }
]