ArcGIS Pro

Update attribute field aliases from a lookup table in ArcGIS Pro

Data dictionaries. Lookup tables. Codebooks. While the name for a dataset’s documentation might vary across professions and data sources, the need for data documentation is universal! A common way to store this type of metadata is in a lookup table or data dictionary. At its simplest, a data dictionary is a two-column table in which one field is the field name, and another is the corresponding definition of what that field name represents.

This type of information can be stored on each field as the alias. An alias is an alternative name for a field providing a more user-friendly description of the content. Aliases are much more accommodating than field names, as they can contain up to 255 characters, including spaces and special characters, and even start with numbers. By applying aliases, you can give names to fields that are more descriptive than their actual field names.

Benefits of applying field aliases

The many ways that field aliases make your data easier to work with include:

In short, applying field aliases is good data management. It’s possible to set these field aliases using the handy dandy lookup table manually, which can take a whole afternoon. With this approach, there’s always the chance for human error, and the chance of getting a repetitive motion injury! Instead, we can use use this bulk-assign alias script tool to do this systematically.

What is a script tool?

Script tools are geoprocessing tools that execute a script or executable file. Script tools allow you to run these scripts from within ArcGIS, using a geoprocessing tool as the interface to the functionality in your script. When you create a script tool, you specify parameters that your script needs to execute. The most common parameters are input and output datasets, field names, and strings chosen from a choice list. When the script tool is run, the parameter values are passed to your script and used by your script during execution.

Almost all script tools execute a Python script (.py) that uses ArcPy, a Python site package installed with ArcGIS. ArcPy provides access to geoprocessing tools as well as additional functions, classes, and modules that allow you to create simple or complex workflows quickly. Through ArcPy, your script can access the geoprocessing environment of ArcGIS, providing benefits such as validation of inputs, error messages, and recording of history.

You can create your own script tool for your specific use-case by first writing a script with parameters. (While most script tools are written in Python, you can create a script tool for an .r.bat, or .exe file that accepts arguments.) We created a script and accompanying script tool to bulk-assign aliases from a lookup table. We’re using a script tool in a Python toolbox rather than a custom toolbox, which is why it has the extension of .pyt. We are excited to share this tool with you!

A script tool that can bulk-assign aliases

The inspiration for this script tool comes from the geodatabase files containing American Community Survey data made available from the U.S. Census Bureau. These geodatabases contain a polygon file with boundaries, a metadata table which has two fields (Short_Name and Long_Name), and then 32 tables with a few hundred fields in each.

Here’s the metadata table:

A two-column table. First column is called Short_Name and contains the cryptic field names such as B01001e1. Second column is Full_Name and contains a descriptive field alias.

Here’s an example of one of those 32 attribute tables:

Tables whose fields have cryptic field names such as B01001e1, B01001m1, B01001e2, B01001m2, etc.

The field names of these tables are the Short_Name in the metadata table. We wanted to apply the corresponding Long_Name as the alias. Taking advantage of the tool, we wrote a script that bulk-assigns aliases to the table of your choice.

How can I use this tool?

First, decide if you want to run the stand-alone script in the Python window, or if you want to use the script tool. The stand-alone script will run much faster, but the script tool allows you to point-and-click your way to running the tool, since it’s essentially a custom geoprocessing tool.

Step 1. Download either the stand-alone script, or the Python toolbox containing the Bulk Assign Aliases script tool. Save and extract the files in your Pro Project’s folder.

Step 2. Within the Catalog Pane, navigate to the stand-alone script or the tool in your folder connections. (You can also see the stand-alone script by right-clicking the script tool and selecting Edit.)

Within your folder connections, expand the toolbox and see the script tool called Bulk Assign Aliases.

Step 3. If running the script tool, set the parameters you want.

Input attribute table: X01_AGE_AND_SEX. Input lookup table: TRACT_METADATA_2018. Short name field: Short_Name. Long name field: Full_Name.

Step 4. Run the tool or the script, and be patient. It will most likely take some time.

Step 5. Open up your attribute table, and see your fields with aliases:

Aliases show up throughout ArcGIS Pro and ArcGIS Online

Aliases show up when working with the data, such as when selecting by attributes.

They also appear when displaying your data in charts, legends, and infographics.

Aliases are preserved when publishing your maps and layers to ArcGIS Online. Applying field aliases to your fields early on makes downstream work easier. Use use this bulk-assign alias script tool to assign aliases from a lookup table in a systematic way.


Update on 3 August, 2022: This script tool requires that the long names (aliases) be 255 characters or fewer. Many of the official long name values will need to be modified. The “find and replace” option in the table view can help to remove strings such as ” — (Estimate)” and ” — (Margin of Error)” which can help. There are no plans to update this script tool at this time.

About the authors

(she/her/hers) Diana loves working with data. She has over a decade of experience as a practitioner of demography, sociology, economics, policy analysis, and GIS. Diana holds a BA in quantitative economics and an MA in applied demography. She is a senior product engineer on ArcGIS Living Atlas of the World's Policy Maps team. Diana enjoys strong coffee and clean datasets, usually simultaneously.

Gonzalo Espinoza is a Senior Product Engineer at ArcGIS Living Atlas of the World. Gonzalo specializes in hydrologic modeling, real time climate and hydro-informatic tools such as flood mapping and forecasting using National Water Model data. He masters the full geospatial tech stack required to develop scalable and operational services relying on large volumes of EO data in the fields of water and environment. At Living Atlas, he also supports the development of workflows for automation of data updates known as Live Feeds, technology used at Esri’s Disaster Response Program. Before ESRI Gonzalo worked in the development of Water Accounting at UNESCO IHE. Gonzalo has been active professionally and academically, being the runner up in the entrepreneurial innovation bootcamp of the European Space Agency (ESA), and he has published applied research papers related to water balance and fluxes in the Amazon Basin and in the Middle East. He holds a PhD in Civil Engineering from the University of Texas at Austin.

Inline Feedbacks
View all comments

Next Article

Pop-ups: the essentials

Read this article