Table Metadata Sync Trigger API

Description

Alation synchronizes physical metadata (through Metadata Extraction) on a batch basis, scheduled by the administrator. A full metadata extraction can be expensive, so it is sometimes scheduled only hourly or weekly. This means that when a table is created or altered, it may take a long time for the Alation catalog to be updated.

With this API, you can request synchronization of physical metadata for a single table. When you make a POST request, the Alation server connects to the target data source and requests the metadata for the specified table and its columns, updating the Alation catalog appropriately.

The following operations are supported:

1. POST: Trigger synchronization of a table.

NOTE: This API is available in version 4.11 and later.

Trigger synchronization of a table

This API triggers an immediate synchronization of the physical metadata for the specified table and its columns.

URL

POST /api/v1/table/sync/

Data Parameters

Name	Required	Type	Description
datasource_id	Yes	Integer	Unique identifier of an existing data source in Alation.
schema	Yes	String	The name of the schema (sometimes referred to as "catalog" or "database") of the desired table. See note below for databases with a four-level hierarchy.
table	Yes	String	The name of the desired table
table_type	No	String	One of "VIEW" or "TABLE". Default is "TABLE"

NOTE: Some data source types (such as SQL Server) have two levels of grouping above tables instead of just one. You will need to include both names separated by a '.' in the schema field. See Multipart Schema Names for more.

Sample Request Body

{
    "datasource_id": 8,
    "schema": "main.dbo",
    "table": "foobar",
    "table_type": "VIEW"
}

Headers

HTTP Header	Value
Token	<your_token>
Content-Type	application/json

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

Success Response

Content-Type: application/json

Status: 201 CREATED (This is the response status even if the table was already in the catalog.)

Response Headers:

Name	Value
Location	/api/table/<id>

Body

{
    "id": 17194,
    "url": "/table/17194/",
    "name": "articles",
    "schema_name": "objects",
    "title": "Articles",
    "description": "<p>Contains one row for each Article ever created in Alation</p>\n",
    "ds_id": 107,
    "is_view": true,
    "custom_fields": [],
    "schema_id": 773,
    "synonyms": null,
    "db_comment": null
}

Name	Description
id	Alation ID of the created or updated table catalog entry
url	URL of the Alation catalog page for the created or updated table
name	Name of the table
schema_name	Name of the table's schema
title	Alation title of the table
description	Alation description of the table
ds_id	Alation ID of the table's data source
is_view	True if the table is a view. False if it is a regular table.
custom_fields	Field descriptions and values of any fields on table objects in Alation
schema_id	Alation ID of the table's schema
synonyms	Synonyms for this table extracted from the database. Supported by a minority of data source types.
db_comment	Comment for this table extracted from the database. Supported by a minority of data source types.

Error Responses

Status	Reason
400 BAD REQUEST	Body is missing a required value
400 BAD REQUEST	Bad value for `table_type`
400 BAD REQUEST	Selected schema is excluded from the catalog (see Per-Object Settings in Data Source Settings)
403 FORBIDDEN	You are not authenticated
403 FORBIDDEN	You are not an admin
403 FORBIDDEN	The configured Service Account for the data source does not have permission to view the metadata of the table (may require SELECT privilege)
404 NOT FOUND	Data Source or Schema is invalid
404 NOT FOUND	Table not found in data source
500 INTERNAL SERVER ERROR	There was an error connecting to the data source (e.g. timeout, port blocked, etc)

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/table/sync/"

# Synchronize objects.articles in Alation DB
curl -X POST "${BASE_URL}" -H 'content-type: application/json' -H "Token: ${API_TOKEN}" -d '{
        "datasource_id" : 6,
        "schema" : "objects",
        "table": "articles",
        "table_type": "VIEW"
    }'

Python

import requests
import json

# This is an example token. Please replace this with your token.
headers = {'Token': '2abcd-4c04-4c21-8692-eda27a877f90'}

data = {
    'datasource_id': 6,
    'schema': 'objects',
    'table': 'articles',
    'table_type': 'VIEW'
}

# Synchronize objects.articles in Alation DB
response = requests.post('https://alation.yourcompany.com/api/v1/table/sync/', data=data, headers=headers)
table = json.loads(response.text)
print "ID: %s, Name: %s" % (table['id'], table['name'])