Enforce one-to-one joins between research table revisions — what should the operator record?
A one-to-one comparison is useful only when each side actually has at most one row per qualified key. Duplicate inputs can multiply rows and make every later difference harder to interpret. Validate cardinality first, then compare fields while keeping unmatched and conflicting records visible as separate operational states.
Reject duplicate-key matches before reconciling fields from two authorized outputs.
Record left_revision, right_revision and qualified_join_key, stating that each side must contain no more than one row per key. A receipt may contain repeated observations of one source object; if so, choose an observation-level key or a reviewed reduction before declaring source-key uniqueness.
Publish matched, left-only and right-only states with actual checked counts, avoiding a claim that unmatched returned records were absent from the source population. Include unresolved duplicate-key exceptions alongside unmatched keys, making clear whether the comparison is complete for the declared returned inputs or only a validated subset.Declare the identity grain
Record left_revision, right_revision and qualified_join_key, stating that each side must contain no more than one row per key. A receipt may contain repeated observations of one source object; if so, choose an observation-level key or a reviewed reduction before declaring source-key uniqueness.
Validate uniqueness first
Build duplicate-key exception lists for both inputs before performing the join, preserving conflicting rows for authorized inspection. Two identical-looking duplicate rows still violate the declared grain until the duplicate handling rule is applied explicitly; do not let a join library choose behavior silently.
Test contract violations
Use fixtures with one duplicate on either side and verify the operation blocks or quarantines it rather than selecting the first row. The test should check output multiplicity as well as key presence, because a many-to-many expansion can retain every key while creating unsupported repeated comparisons.
Compare matched fields
Keep left_value and right_value separate for meaningful differences, with a comparison_state that distinguishes null from an actual changed value. Use comparison states such as equal, changed, left-unavailable and right-unavailable rather than subtracting or concatenating unlike fields into one confusing difference cell.
Release reconciled membership
Publish matched, left-only and right-only states with actual checked counts, avoiding a claim that unmatched returned records were absent from the source population. Include unresolved duplicate-key exceptions alongside unmatched keys, making clear whether the comparison is complete for the declared returned inputs or only a validated subset.
Keep the boundaries clear.
- Reject duplicate-key matches before reconciling fields from two authorized outputs.
- Operational record: Declare the identity grain. Context badges do not certify access.
Start with a read-only check: ask your agent to report actual source coverage before collecting records or exporting an audience.
Primary references
Documentation reviewed 2026-11-15. Product capabilities, client availability and plans can change. Third-party marks identify their products, not an affiliation.