HomeGuidesRecipesAPI ReferencePython SDK
Alation Help Center

Table Metadata Sync Trigger

Table Metadata Sync Trigger API


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.


POST /api/v1/table/sync/

Data Parameters

datasource_idYesIntegerUnique identifier of an existing data source in Alation.
schemaYesStringThe 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.
tableYesStringThe name of the desired table
table_typeNoStringOne 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"


HTTP HeaderValue

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:



    "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
idAlation ID of the created or updated table catalog entry
urlURL of the Alation catalog page for the created or updated table
nameName of the table
schema_nameName of the table's schema
titleAlation title of the table
descriptionAlation description of the table
ds_idAlation ID of the table's data source
is_viewTrue if the table is a view. False if it is a regular table.
custom_fieldsField descriptions and values of any fields on table objects in Alation
schema_idAlation ID of the table's schema
synonymsSynonyms for this table extracted from the database. Supported by a minority of data source types.
db_commentComment for this table extracted from the database. Supported by a minority of data source types.

Error Responses

400 BAD REQUESTBody is missing a required value
400 BAD REQUESTBad value for table_type
400 BAD REQUESTSelected schema is excluded from the catalog (see Per-Object Settings in Data Source Settings)
403 FORBIDDENYou are not authenticated
403 FORBIDDENYou are not an admin
403 FORBIDDENThe configured Service Account for the data source does not have permission to view the metadata of the table (may require SELECT privilege)
404 NOT FOUNDData Source or Schema is invalid
404 NOT FOUNDTable not found in data source
500 INTERNAL SERVER ERRORThere was an error connecting to the data source (e.g. timeout, port blocked, etc)

Code Samples


# This is an example token. Please replace this with your token.


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


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'])