Skip to main content

Choose a Stable Table Key

Data model · Key

Give every identifiable API record a stable identity so NIM can collect, relate, and update it reliably.

What key doesDirect link to what-key-does

The optional key property names the resource that uniquely identifies a row in this NIM table. In most connector tables you should define one, and the NIM Studio table key should match it.

"users": {
  "key": "id",
  "resources": {
    "id": "string*",
    "displayName": "string*",
    "email": "string"
  }
}

key must refer to a resource defined in the same table's resources object.

Choose the right identifierDirect link to Choose the right identifier

PreferAvoid
An immutable API-generated IDA display name or other editable label
A value returned for every recordA value that can be blank or omitted
A value unique across the tableA department, location, or other repeated attribute
A value accepted by detail, update, or delete endpointsAn identifier usable only in a list response

An email address can be a useful business identifier, but it is usually a poor table key because people change it. Prefer the API's internal ID and collect email as a normal resource.

Validate before enabling writesDirect link to Validate before enabling writes

  1. Collect a representative sample of records.
  2. Confirm the chosen value is present and unique for every row.
  3. Confirm it remains stable after an update such as a name or email change.
  4. Confirm the API uses the same value in its detail, update, and delete paths.
  5. Set the matching key in the NIM data model.
Do not change a published key casually

Changing a key after collections, relations, or mappings are configured can break record matching. Treat a key change as a data-model migration and test it in a non-production environment first.

When no key existsDirect link to When no key exists

Some API responses represent junction data, events, or transient results rather than a single identifiable record. You can omit key in those cases. For example, a group-membership table uses its group membership configuration to relate users and groups instead of declaring one table key.

Next: define the table's operations.

Last updated on