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.
: The interface for defining and validating lookups is changing. This topic shows the interface used to make lookups from:
To learn how to use the interface for create a lookup field in a list, assay design, sample set, data class, or other users of the new user interface, see this topic:
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.
- If the field you want doesn't already exist, add it, providing a name and label.
- Click the dropdown under Type and select Lookup.
- In the popup dialog select the folder, schema, and table to use as the target of the lookup. For example, the lists schema and the Languages table, as shown below.
- Click Apply.
- 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 definition editor of the dataset or list with the lookup column.
- Select the lookup column in the table.
- Click the Validators tab.
- Click the button Add Lookup Validator.
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.