Natural keys and lookups
A record can be addressed by a readable key such as about-us as well as by its id. Lookups add further unique keys to a model, so a handle or a SKU finds the record in one typed query.
Natural keys
A natural key is an optional, human-readable address for a record, returned as _naturalKey. It is one URL-safe segment made of letters, digits, hyphens, underscores, full stops and tildes. You can read a record by its key in GraphQL, the SDK and the CLI, and a read that matches nothing returns null. The key is always available to filter and sort on.
Collisions and renames
Set the key when you create the record. If another record of the model already holds it, the create still succeeds and Fóir appends a suffix (about-1, about-2), so read the key back from the response. Renaming is a separate mutation. It is refused when another record holds the new key, and the record's id never changes.
Lookups
A lookup is an extra named key on a model, declared in your config file with keyBy. Each one generates a typed query that returns one record or null: a lookup on a product's SKU gives you productBySku. A lookup can combine up to four fields, and a model can have up to four lookups. The fields must be top-level text, integer, decimal, boolean or enum fields.
A lookup query matches the value of the variant the caller is being served, and takes a locale argument.
Uniqueness and backfill
Lookups are unique and indexed. Saving a record whose lookup value collides with another's is refused, and the error names the model, the lookup and its fields. The console flags the clash inline.
Adding a lookup to a model that already has records backfills it on push. If existing records hold duplicate values, the push stops and the lookup is not added.
Read the detail
The lookups guide covers declaring a lookup, the query it generates, composite keys and conflict errors.