Download a Data Dictionary

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

A data dictionary in Alation is a consolidated summary of all titles, descriptions, and custom field values that exist for a data source and its child data objects. The data dictionary file can be generated on demand by users. To export this information for analysis, you can download the data dictionary. You can also use the data dictionary download as a first step in bulk-updating the data source information. You can upload a data dictionary from a source file, either created from scratch or from an edited downloaded file, to complete the bulk-update.

Note

Data dictionaries are only available for RDBMS data sources, that is, sources that connect Alation to databases.

You can download a data dictionary at the data source, schema, or table level. For example, you can download a data dictionary for one schema and its child tables or one table and its child columns. There is no ability to download the dictionary for one single data object without child objects if it has them.

Download a Dictionary

Note

If you are a Server Admin, be advised that certain aspects of the data dictionary download vary by Alation version.

  • Versions prior to 2023.3: Users can proceed with the instructions provided below.

  • Versions 2023.3 and 2023.3.1: Version 2023.3 introduced a new data dictionary download experience that is enabled by default. It features a new column, al_datadict_item_properties, in the downloaded data dictionaries, which may cause issues for users when they upload data dictionaries in these versions. The issues are caused by the change in the default server configuration for data dictionaries. Refer to Troubleshoot Data Dictionary Download and Upload for more details.

  • Versions 2023.3.2 and newer: The known issue has been resolved. The download and upload processes for data dictionaries have been significantly improved. Users simply follow the steps below to download data dictionaries.

To download a data dictionary:

  1. Sign in to Alation and open the catalog page of a data source. If you want to download the complete data dictionary for this data source and all its child data objects, download from the data source page. If you need the data dictionary for one particular child data object (for example, one of the schemas or tables), then navigate to the catalog page of this data object and download from there.

  2. In the upper-right corner, click More, and then click Download Dictionary:

    ../../_images/DataDict_DataMenu.png

  3. The Download Dictionary dialog opens.

    ../../_images/DataDict_DownloadDictionaryDialog.png

  4. In the dialog, select one of the available file formats—CSV, XML, or JSON—and click Confirm. The download occurs asynchronously; a message appears informing you that the data dictionary is being processed and that an email confirmation will be sent when the data dictionary is ready for download:

    ../../_images/DataDict_DownloadInProgress.png

    If you already have a download in progress, an alternative message appears informing you of that fact:

    ../../_images/DataDict_DownloadAlreadyInProgress.png

  5. When the data dictionary is ready for download, you receive an email containing a link to the prepared data dictionary. Click the link. If you are already signed in to Alation, the file is downloaded. If you are not signed in to Alation, the sign-in page opens when you click the link. The download occurs only after you sign in. The file is downloaded using the browser.

Failure During a Data Dictionary Download

If there is a problem with the download job, an email notification is sent to the user as depicted in the screenshot.

../../_images/DataDictionary05.png

Potential Issues During Data Dictionary Download

A few issues that might occur while accessing the data dictionary download are the following:

  1. The download file is stored on the server for only five days. If you sign in to Alation and click the data dictionary download link five days after creating it, the download file will not exist and there will be a “link expired” error message.

  2. If you sign in to Alation and click the download link and the file exists, but the signed-in user is different from the user who requested the download, the following warning is displayed: “You need access to view this page”.

  3. You can create only one data dictionary export at a time for any object or data source. You cannot queue a data dictionary export for the same data source multiple times when an export is already running. If you try to create another export on the same data source or object while a previous export is running, you see a warning that an export is already in progress.

Data Dictionary Structure

Note

The set of columns in a downloaded data dictionary depends on the Alation version.

  • Any data dictionary you download will include the key, title, and description fields, and custom fields.

  • Starting in version 2023.1, the column al_datadict_item_column_data_type was added.

  • Starting in version 2023.3, the column al_datadict_item_properties was added. From this version onward, any data dictionary you download will include the al_datadict_item_properties, al_datadict_item_column_data_type, key, title, and description fields, and custom fields.

The al_datadict_item_properties Field

Starting in version 2023.3, a column al_datadict_item_properties appears as the leftmost column of downloaded data dictionaries. This is a reserved system column that stores object IDs and object types for all entries in the data dictionary. This column should be considered read-only. Do not modify or update it.

The al_datadict_item_column_data_type Field

Starting in version 2023.1, a column al_datadict_item_column_data_type appears as the first or second leftmost column of downloaded data dictionaries. This is a reserved system column that stores data types for all entries in the data dictionary that have this property. This column should be considered read-only. Do not modify or update it.

Key

key is the qualified name of a data object in Alation which both identifies it and points to its “place” in the structure of the parent data object.

For example, ins.all_claims.claim_id is the key for the column claim_id in the table all_claims in the schema ins in the data source the data dictionary of which is exported. The names of parent and child objects are separated with a dot.

The data source itself uses an empty key value.

Key Format Summary

Object

Key

data (for data sources)

”   “

schema

“schema_name”

table

“schema_name.table_name”

attribute (for columns)

“schema_name.table_name.attribute_name”

Title, Description, Custom Fields

  • title is the Title field of the data object

  • description is the Description field of the data object

  • Custom fields are the custom fields on the templates of the parent object and its child objects (schemas, tables, columns). For more information about templates and custom fields, see Creating Custom Fields for Catalog Pages.

The data dictionary does not include any technical metadata (such as the database name, schema types, table types, or data types).

Example

Assume there is a data source in Alation that has one schema with two tables and two columns each. The data dictionary you can download from the catalog page of this data source will include the fields associated with the catalog templates of the data source itself and those for the child schema, tables, and columns.

Note

Custom field values that are propagated from catalog sets are not included in data dictionaries. For more on catalog sets, see Catalog Sets.

Empty Values and N/A’s

In some fields of a data dictionary file, you may see empty values and N/A values.

  • An empty value—an empty space separated by the delimiter—means that the field does exist for the data object described by this current line of the dictionary, but the value has not been filled. Also the values propagated from catalog sets will be reflected as empty values.

  • The N/A value can mean:

    • The given field is not associated with this particular data object template and the value does not exist for this data object.

    • The user does not have permission to view this field.

Example

The following data dictionary lines (CSV):

key,title,description,executive summary,short description,countries,department
,Redshift,,N/A,N/A,"[""Germany"", ""Canada"", ""Korea""]",N/A

mean that:

  • There is no key value for the data object described by this row of values (it is a data source)

  • There is also no description (empty value)

  • The fields executive summary, short description, and department either do not apply to this data object and do not exist on its page template in Alation or the user does not have permission to view them.