Alation Data Explorer

Overview

Alation’s partners would like to add Alation’s data discovery features to their offering by providing access to Alation’s Catalog UI in their product at the moment of selecting a data object to work with. Alation can become a data application’s equivalent of the Mac Finder or Windows File Explorer modal that appears upon selecting File > Open.

An application developer can create a webview or an iframe that will load a page from the customer’s Alation instance. That page will provide a search and browse interface over the Alation catalog, with a select button. When the select button is clicked, information about the selected object is made available to the parent application.

Implementation

Alation provides a Javascript SDK to launch and receive events from Alation Embeddable CatalogChooser. For other programming environments (e.g. Windows or Mac native apps), please contact an Alation representative for more details on the integration.

Including the SDK

The SDK is hosted on the Alation instance itself. You will need to know the URL of the Alation instance in order to load the SDK. This includes the scheme (HTTP or HTTPS, depending on how the customer has configured it), domain, and port. Once you have this information, add a script tag to your application to load the SDK:

<script type="text/javascript"
src="<scheme>://<domain>:<port>/integration/catalog_chooser/v1/sdk.js" />

When the script loads, it will add a global Alation object that can be used to access the SDK functions.

Creating the View

To initialize the Alation Embeddable CatalogChooser view, use the createChooser function:

var alationCatalogChooser = Alation.Catalog.createChooser({
      embedMethod: Alation.Catalog.ChooserEmbedMethod.MODAL, // How to open the chooser (currently MODAL or CUSTOM)
      onSelect: function (data) {}, // Callback for when user selects an object
      onCancel: function () {}, // Callback for when the user cancels
      acceptObjectTypes: [] // List of acceptable oTypes (empty == all)
});

Embed Method

Alation provides a convenient method for opening the chooser in a modal, with some default styling. This is the default embedMethod.

If you prefer not to use the modal you can choose the CUSTOM method and attach the Chooser element however you’d like. Note, alationCatalogChooser.open() will throw an error in this case.

var alationCatalogChooser = Alation.Catalog.createChooser({embedMethod:
ChooserEmbedMethod.CUSTOM});
document.body.append(alationCatalogChooser.element);

If you use the CUSTOM method, the createChooser function will create the DOM element without inserting it into the current document. You can insert it into the document however you wish using the element property on the returned object.

Opening the CatalogChooser

If you have chosen the MODAL embedMethod, you can activate the CatalogChooser by calling alationCatalogChooser.open(). This will reset the iframe to the Alation home page, for users to start at. If using the built-in modal, this will also open the modal for the user to see.

Filtering the object types

Alation’s catalog captures a wide variety of types of objects, from tables to queries to articles to users. In any particular instance, your application may only be able to accept certain types of objects. Specify these with the acceptObjectTypes parameter on createChooser.

var alationCatalogExplorer = Alation.Catalog.createChooser({
acceptObjectTypes: [
      Alation.Catalog.ObjectType.TABLE,
      Alation.Catalog.ObjectType.QUERY,
]
});

You can additionally filter to only data objects in particular types of data sources:

var alationCatalogExplorer = Alation.Catalog.createChooser({
  accept DataSource Types: [
      Alation.DataSourceType.BIGQUERY,
      Alation.DataSourceType.DB2,
      Alation.DataSourceType.GREENPLUM,
      Alation.DataSourceType.HIVE2,
      Alation.DataSourceType.IMPALA,
      Alation.DataSourceType.MYSQL,
      Alation.DataSourceType.NETEZZA,
      Alation.DataSourceType.ORACLE,
      Alation.DataSourceType.ORIENT,
      Alation.DataSourceType.POSTGRESQL,
      Alation.DataSourceType.PRESTO,
      Alation.DataSourceType.REDSHIFT,
      Alation.DataSourceType.SAP,
      Alation.DataSourceType.SAS,
      Alation.DataSourceType.SNOWFLAKE,
      Alation.DataSourceType.SQLITE,
      Alation.DataSourceType.SQLSERVER,
      Alation.DataSourceType.SYBASE,
      Alation.DataSourceType.TERADATA,
      Alation.DataSourceType.TERADATAASTER,
      Alation.DataSourceType.VERTICA
    ]
  });

Cleaning up the CatalogChooser

To destroy the CatalogChooser you can use alationCatalogChooser.destroy(), which will remove elements from the DOM and clean up event listeners.

Listening to Events

Embeddable CatalogChooser provides two events:

Cancel event when the user closes the view
Select event when the user selects an object

Handling Cancellation

When a user cancels the selection process from inside the Alation view, the SDK will destroy all DOM elements that
it created. Then it will notify any handlers registered with the onCancel function.

alationCatalogExplorer.createChooser({function () {
console.log("The explorer view is gone");
// Do any other cleanup here
});

If you would like to close the view yourself, you can do so with the destroy function. The onCancel handlers will not be called.

alationCatalogExplorer.destroy(); // Will close the active Chooser Modal

Handling Selection

To listen for selection, register a callback with the onSelect function. It is your responsibility to close and clean up the Alation view with the destroy function.

alationCatalogExplorer.onSelect(function (selectedObject) {
  if (!isValid(selectedObject)) {
  alert("Please select a different object");
  return;
}
alationCatalogExplorer.destroy();
// handle the selection
});

The selected object will be an Alation Object Reference JSON object as defined below.

Alation Object Reference JSON

See the table below for more details and example outputs from a table.

References to objects in Alation will always have the following fields:

otype: Object type, one of those specified in Alation.Catalog.ObjectTypes. Currently one of: table or query.
oid: Alation object ID. These are not unique across object types, so a unique ID requires the otype as well.
catalogUrl: URL for the catalog page for this object in the Alation instance.
apiUrl: URL for the canonical API resource for this object in the Alation instance.
semanticMetadata: The user-contributed metadata captured by Alation. May be null.
title: The user-contributed logical title (short, plain text) in Alation.
description: The user-contributed logical description in Alation (HTML rich text).

Data objects (tables and columns) will have the following additional fields:

qualifiedName: Fully qualified name for relational objects, e.g. [database/catalog.]schema.table[.column].
qualifiedNameParts: Fully qualified name as an array of name parts. Note that if the database has multipart schema names, they are a single entry in this array. e.g.["catalog.schema", "table", "column"].
location: A JSON object with names of this object’s parents.
- schema
- table
- column
tsLastExtracted: A Date() object representing the time Alation last extracted the object.
dataSource: Details about the database, data warehouse, or Hive instance that this object belongs to.
catalogUrl: URL for the catalog page for this object in the Alation instance.
apiUrl: URL for the canonical API resource for this object in the Alation instance.
jdbcUri: URI used to configure the JDBC driver for this data source.
type: A string for the source type, e.g. “Hive” or“MySQL”.
host: IP address or domain name.
port: TCP port.
database: The database name to connect to (usually added after the domain and port in the JDBC URI). May be null.

Query objects will have the following additional fields:

currentSqlText: String of the current text content of the SQL query. May contain multiple SQL statements.
sqlTextApiUrl: An endpoint that returns the current text content of the SQL query, for the client to display or execute.