Resolve Relationships by Natural Key
Source systems reference the other side of a relationship by whatever they hold — a tax identifier, an account number — not by a platform identifier. This is how that becomes a governed link.
Before you start
- Both entity types defined, and a relationship type linking them.
- The attribute holding the natural key defined on the target type.
- The
relationship-resolution-rule.createpermission.
1. Define a resolution rule
Resolution rules are defined against a relationship type, which fixes the direction and cardinality of what they may create.
A rule says: for this relationship type, from this source, the key in this field identifies the target by that attribute.
Choose a key that is genuinely identifying. A rule keyed on something non-unique produces ambiguity on every record rather than links.
2. Ingest the evidence
Load records carrying the reference. Each source's claim is recorded as an assertion in its own right, before any link is made.
This separation is what makes out-of-order loading work: the assertion records what the source said, whether or not the platform can act on it yet.
3. Understand the states
| State | Meaning | Action |
|---|---|---|
| Pending | The target has not been found yet | Wait — it retries as data arrives |
| Resolved | A canonical edge exists | None |
| Ambiguous | The key matched more than one candidate | A person decides |
| Conflicted | The target resolved, but the edge could not be created — most often a cardinality rule blocked it | A person decides |
Nothing is guessed. An assertion that cannot be resolved unambiguously waits rather than picking a candidate.
4. Resolve ambiguity
Assertions waiting on a steward. Nothing here was guessed at — each is evidence that matched more than one candidate, or none.
Ambiguous assertions queue for a steward, who picks the correct target or rejects the assertion.
Recurring ambiguity on one rule is a signal about the rule, not the data: the key is not as identifying as assumed. Fix the rule rather than deciding the same class of case repeatedly by hand.
5. Backfill after a late rule
Activating a rule after evidence has already been ingested triggers a backfill, so assertions recorded before the rule existed are evaluated against it.
Evidence is never discarded for arriving before its rule.
6. Handle succession
When a fact changes — an asset sold, an employment ended — the previous relationship window closes and a new one opens. The history stays intact, and asking who held the relationship at a past date returns the right answer.