Keys

Data identity guide

Keys tell NIM how to reliably identify a record and how other data can refer to it.

A key is a column NIM uses to identify or look up a row in a data table. Good key choices make relations, filters, and Vault queries predictable; poor key choices can create incorrect matches or make records impossible to relate.

Primary keys and reference keysDirect link to Primary keys and reference keys

Key type	How many a table can have	Use it for	Example
Primary key	Zero or one	The table’s main, unique record identifier. NIM uses it as the destination for intra-system relations and relation items in filters.	`employees.employee_id`
Reference key	Zero or more	An additional unique value that can be used to look up or relate records.	`employees.employee_other_id`

The primary key is the default identity of a row. A reference key is useful when an external or alternate identifier is also stable enough to support a relationship or Vault query.

Choose stable identifiersPrefer an immutable, system-generated ID. Avoid names, email addresses, or values derived from organizational structure unless your organization guarantees that they are unique and do not change.

Select a good keyDirect link to Select a good key

Before assigning a column, check that it is:

Unique — each row has a different value.
Present — the value is populated for the records you need to process.
Stable — the value does not change when a person changes name, department, or email address.
Consistent — it uses the same format across all relevant rows and collections.
Appropriate for the table — use the identifier for that record type, not a display attribute from a related record.

For an employee table, a permanent HR employee ID is typically a stronger primary key than email. For a directory user table, an immutable directory object ID is generally more reliable than a display name or user principal name.

Configure keys in the right orderDirect link to Configure keys in the right order

Select the tables and columns you need to collect.
Assign a primary key to each table that needs a main record identity.
Assign reference keys only where an additional unique lookup value is needed.
Configure intra-system relations between the keyed tables.
Collect the system and review the resulting data before using it in filters, mappings, or scheduled jobs.

warning

Do not assign a key to a column with duplicate or frequently changing values. A relation may look valid at first but later connect the wrong records when values change or repeat.

Where keys are usedDirect link to Where keys are used

NIM feature	Why the key matters
Intra-system relations	Connects a foreign-key value in one table to the identified row in another table.
Relation items in filters	Makes related table data available when shaping a filter’s output.
Vault queries	Lets custom JavaScript check or retrieve records by primary key or reference key.
Inter-system design	Helps establish a dependable basis for matching data across different connected systems.

Next stepsDirect link to Next steps

After setting keys, define intra-system relations. If you need to link data from different systems, continue with inter-system relations.