This topic is under construction for the July 2020 release of LabKey Server. For current documentation of this feature, click here.
give you the ability to link data from two different tables. For example, you can create a grid combining data from two tables by reference. One column pulls in data from another table and you can then display values from any column in that target (or "looked up") table. You can also take advantage of a lookup to simplify user data entry by constraining entered values for a column to a fixed set of values in another list.
Set Up a Lookup Field
Suppose you want to display values from the Languages
list, such as the translator information, alongside other data from the Demographics
dataset. You would add a lookup column to the Demographics dataset that used values from the Languages list.
To join these tables, an administrator adds a lookup column to the Demographics dataset definition using this interface:
- Go to the dataset or list where you want to show the data from the other source. Here, Demographics.
- Click Manage, then Edit Definition.
- Click Fields.
- Use to expand the field you want to be a lookup (here "languages").
- If the field you want doesn't already exist, click Add Field at the bottom of the fields panel to add it.
- From the dropdown under Data Type, select Lookup.
- In the Lookup Definition Options, select the Target Folder, Schema, and Table to use. For example, the lists schema and the Languages table, as shown below.
- Scroll down and click Save.
- The lookup column is now available for grid views and SQL queries on the Demographics table.
- You can also create grids merging information from any of the columns of both tables. For example, a grid showing which translators are needed for each cohort would make it possible to schedule their time efficiently. Note that the original "Language" column need not be shown.
For more about creating joined grids see Join Columns from Multiple Tables
Default Display Fields
For lookup fields where the target table has an integer primary key, the server will use the first text field it encounters as the default display column. For example, suppose the Language field is an integer lookup to the Languages table, as below.
In this case, the server uses Language Name
as the default display field because it is the first text field it finds in the looked up table. You can see this in the details of the lookup column shown in the example above, as "English", etc, are displayed though the lookup is to an integer key.
Displaying Alternate Fields
To display other fields from the looked up table, go to (Grid Views) > Customize View
and select the fields you want to display.
You can also use query metadata to achieve the same result: see Query Metadata: Examples
Validating Lookups: Enforcing Lookup Values on Import
When you are importing data into a table that includes a lookup column, you can have the system enforce the lookup values, i.e. any imported values must appear in the target table. An error will be displayed whenever you attempt to import a value that is not in the lookup's target table.
To set up enforcement:
- Go to the field editor of the dataset or list with the lookup column.
- Select the lookup column in the Fields section.
- Expand it by clicking the .
- Under Lookup Validator, check the box for Ensure Value Exists in Lookup Target.
Note that pre-existing data is not
retroactively validated by turning on the lookup validator. To ensure pre-existing data conforms to the values in the lookup target table, either review entries by hand or re-import to confirm values.