Upload Lexicon Manually¶

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

The Lexicon feature in the Alation platform allows users to define expansions for abbreviations commonly found in database object names. These expansions help Alation automatically generate readable and meaningful titles for those objects.

You have the ability to manually upload Lexicon information that is not already captured by extracting metadata from connected data sources from a CSV file. Alation provides a command-line script for uploading Lexicon. This process adds new abbreviations and expansions to the existing Lexicon dictionary.

The following step-by-step instructions explain how to use the script. You must have the Server Admin role to perform these steps.

Note

Alation Cloud Service customers will need to contact Alation Support to upload Lexicon manually as the script is run on the backend of the Alation server.

Step 1: Prepare the Input CSV File¶

Alation expects the information for upload in the CSV format.

The input CSV file must contain two columns:

First column: Abbreviation to be added (or already present) in the Lexicon.

Second column: Expansion corresponding to the abbreviation. Multiple expansions for a single abbreviation must be provided on separate lines.

Additional Guidelines¶

A header row is not required.
The input file should not contain empty rows.
If your CSV file includes Unicode characters, ensure it is saved with UTF-8 encoding.

Important

Each abbreviation must be a single word containing only letters or only numbers, not a combination of both. Abbreviations that include special characters or combine multiple words (for example, rgnl_sls) are not supported and will be skipped during processing. In the latter case, break the abbreviation down and put each part on a separate row. For example, instead of rgnl_sls, submit:

rgnl,regional
sls,sales

Example input file

amt,amount
cst,cost
cst,customer
bal,balance

Step 2: Copy the Input File to Alation Server¶

After preparing the CSV file, transfer it to a temporary directory on the Alation server using your preferred file transfer method (like FileZilla, scp, or sftp). If necessary, consult your Alation instance administrator for details such as the server address and login credentials.

Once the file is transferred to a temporary directory on the server, move it to the /opt/alation/alation directory, using:

sudo mv /<temp_directory>/<input_file>.csv /opt/alation/alation/

Step 3: Change Ownership to alation¶

Ensure the file is owned by the alation user. If you used a different account to transfer the file, update ownership with the following command:

sudo chown alation:alation <input_file>.csv

Step 4: Log in to the Alation Shell¶

Access the Alation shell with the following command:

sudo /etc/init.d/alation shell

Successful login will produce output similar to:

This is an Alation shell on a production server. If you got here in error, use ^D to exit.

Mounting into root jail...
Data disk already mounted.
Backup disk already mounted.
/dev already mounted.
/proc already mounted.df
Copying configuration files into the root jail...
(env) PROD [alationadmin@ip-10-11-3-174 /]$

Step 5: Log in to the Django Shell¶

From the Alation shell, enter the Django shell by running:

alation_django_shell

Step 6: Execute the Upload Lexicon Script¶

Import the upload script.
from lexicon.upload import upload_csv
Set the file path. Replace <input_file_name> with your actual file name.
path_to_file = '/<input_file_name>'
Run the script. Replace <userID> with the ID of a Server Admin user.
upload_csv(path_to_file, <userID>)
Note

You can find your userID at the end of the URL on your Alation profile page. For example, if the profile URL ends with /user/99/, then your userID is 99.
Exit the Django shell:
exit()
Exit from the Alation shell:
exit