How references connect entries

A reference is a field that links an entry to an entry in another collection. It stores the link, not a copy: when you read the entry, the referenced entry comes with it as it is now, so a change on one side is seen everywhere that points at it.

Requirements

None to read this page. To add a reference field: a role that can edit the collection's fields.

A link, not a copy

A reference (elsewhere: lookup, linked record, relation) is how a placement at a staffing firm knows which client it is for, and which candidate fills it. The placement does not hold the client's name and address; it holds a pointer to the client entry. Rename the client and every placement shows the new name, because there is only one client entry to change.

That is the difference from typing the client's name into a text field. Text drifts: two people spell it two ways, and nothing connects the placement to the client's other placements. A reference keeps one source for each fact.

The kinds of reference

• Reference: points at one entry. A placement has one client.
• Multi-reference: points at several entries at once. A job opening lists several recruiters working it.
• References into several collections: one field that can point at an entry in any of a set of collections you choose. A task can be about a client, a candidate, or a placement, without three separate fields.
• Parent: points at another entry in the same collection, for hierarchies such as a parent company and its subsidiaries. A reference cannot point at its own collection, so this is the field for that shape.

When to choose one reference or several is covered in Reference vs multi-reference.

Reading across a reference

A reference is read from both directions, in different ways.

• Forward, from the entry that holds the link: open a placement and the client is there, with its current fields.
• Backward, from the entry being pointed at: a client does not hold a list of its placements. Instead, you filter the Placements collection by that client, or add a rollup to the client that counts or sums its placements. A lookup goes the other way, showing one field of the client on each placement. See Rollup vs lookup.

This is why the link belongs on the many side: each placement points at its one client, and the client reads its placements back.

Rules on a reference

A reference can carry a rule that narrows which entries it accepts. On a work order, the vehicle can be limited to the vehicles that belong to the customer already chosen. A value outside that set is refused when the entry is saved.

Notes and limitations

• Archived targets. If a referenced entry is archived, the reference reads as empty, and it drops out of a multi-reference's list. The link itself is not rewritten.
• The target is not checked on save. Outside of rules like the one above, saving an entry does not confirm that the referenced entry exists. In the interface you pick from existing entries, so this matters mainly for imports and agents.
• No self-reference. A reference or multi-reference must point at a different collection; use a parent for hierarchies inside one collection.
• Type is fixed. A reference cannot later become a multi-reference; that change means a new field and a data migration.

Related

For when a connection deserves its own collection, see New collection vs new field; for a worked many-to-many case, Modeling compatibility between products and equipment. For typed relationships between peers that carry a role, such as a contact's part in a deal, see Entry links.