Assign reference keys to tables
Data-model setup · Optional step
Add a reference key only when a table needs an additional stable, unique value for a lookup or relationship.
A reference key is an extra identifier on a data table. Unlike the one primary key that identifies the table’s main record identity, a table can have multiple reference keys. NIM can use them for relationships and Vault queries when the primary key is not the value you need to look up.
For the difference between primary and reference keys, see Keys.
When to add a reference keyDirect link to When to add a reference key
Add a reference key when all of these are true:
- The table already has an appropriate primary key.
- You need to reliably look up records by a second identifier.
- The second identifier is unique, populated, stable, and consistently formatted.
- A filter, relation, integration requirement, or Vault query needs that specific value.
| Good use | Usually not a good use |
|---|---|
| An alternate immutable external ID used by another system | A display name used only for readability |
| A unique legacy ID required for a controlled lookup | An email address that can change during account updates |
| A unique code consistently present in every relevant record | A department, title, or location value shared by many people |
Assign a reference key in NIMDirect link to Assign a reference key in NIM
- Expand the system’s table list.
- Open the table that contains the alternate identifier.
- Select the Columns tab.
- Mark the selected column as Reference.
- Select Save.
- Repeat only for other tables or identifiers that need an alternate lookup key.
Validate before useDirect link to Validate before use
- Collect and load the system.
- Inspect sample records to confirm the reference value is present and unique where expected.
- Check its format against the value that filters, relations, or Vault queries will provide.
- Test the dependent workflow using representative records, including a no-match case.
Do not mark a column as a reference key if duplicate or blank values are expected. Use a normal collected column and choose a different matching approach instead.
Next stepsDirect link to Next steps
Continue with Specify intra-system relations when the key connects tables in the same system. For an alternate-record lookup in a calculated field, see Vault queries.