Data Dictionary Structure

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

Data dictionary files you download have a structure that reflects the field composition of catalog templates. A data dictionary includes a number of non-editable metadata fields, the title and description built-in fields, and all potentially editable custom fields present on the catalog templates of the parent and child objects.

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.

A downloaded data dictionary file in the CSV format will look similar to the following example (version 2024.1.3):

../../_images/DataDict_CSVFileExample.png

A downloaded data dictionary file contains these fields:

al_datadict_item_properties

Present in version 2023.3 and newer

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.

al_datadict_item_column_data_type

Present in version 2023.1 and newer

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

All Alation versions

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 whose data dictionary was exported. The names of parent and child objects are separated with a dot.

The data source (data) object uses an empty key value.

Key Format Summary

Object Type

Key

data (for data sources)

" "

schema

"schema_name"

table

"schema_name.table_name"

attribute (for columns)

"schema_name.table_name.attribute_name"

title

All Alation versions

The title field is the Title built-in field of the object.

description

All Alation versions

The description is the Description built-in field of the object.

Custom Fields

All Alation versions

Custom fields are fields on the templates of catalog objects (data sources, schemas, tables, columns) that were added by Catalog and Server Admins when curating those templates for all users. Custom fields store relevant information about catalog objects and can be updated by catalog users with appropriate permissions. Values in custom fields can be unique to an object or group of similar objects. For more information about templates and custom fields, see Create Custom Fields for Catalog Pages.

The data dictionary does not include technical metadata that is usually found in built-in catalog fields (such as the database name, schema types, or table types). An exception is column data type (the al_datadict_item_column_data_type field).

Note

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

Understand Empty Values

You may see absent values and N/A values or underscore symbols in a downloaded data dictionary file. The representation of absent values depends on your Alation version.

  • An empty field—a blank—In all Alation versions, indicates an updatable field that exists on the template of the object described by this current line of the dictionary, but with no value filled yet. Users can provide a value instead of a blank when editing the file.

  • An underscore (version 2024.1.2 and newer) or N/A (versions before 2024.1.2), indicates either of the following:

    • The field cannot be viewed by the user who downloaded the dictionary (this user doesn’t have a minimal level of access to the field, which is view permission).

      Note

      During the data dictionary download, Alation checks view permission on the fields and adds the underscore symbol (_) if the user doesn’t have view permission. However, if the user has view permission but doesn’t have edit permission, the field will appear as an empty field (blank).

    • The field doesn’t exist on the template of the object described by this current line of the dictionary.

    • The value of the field is propagated from a catalog set.

      Format

      A blank value (updatable)

      An absent value or non-existent field (2024.1.2 and newer)

      CSV

      ,,

      ,_,

      XML

      <description />

      <test>_</test>

      JSON

      "document:user": ""

      "test:glossary_term": "_"

For example, let’s look at the following lines from a data dictionary CSV file in version 2024.1.3:

al_datadict_item_properties,al_datadict_item_column_data_type,key,title,description,executive summary,short description,countries,department
oid=1;otype=data,,,Redshift,,_,_,"[""Germany"", ""Canada"", ""Korea""]",_

In this example:

  • There is no value for al_datadict_item_column_data_type (empty value)

  • There is no key value (empty value)

  • There is no description (empty value)

  • The fields executive summary, short description, and department either don’t exist on this catalog page template, or the user does not have permission to view them, or they are propagated from a catalog set.