Merger Rules for Arrays of Objects (Key-Based)
The Semantic Modeler merge rules described in this topic apply to arrays
containing objects like joins or logical columns identified by a unique key field, for
example name, id, or rightTable. Semantic
Modeler's merge strategy uses this key, and not position, to match objects across branches.
Merge Semantics
This section describes how Semantic Modeler's merge strategy evaluates and merges object-level changes.
- Merges objects based on their identity using key-based matching.
- Always merges additions with distinct keys (union).
- Generates conflicts only when both branches modify the same keyed object incompatibly.
- Preserves order when changes don't conflict. Otherwise resolves order deterministically.
- Treats a rename as a delete-and-add operation unless both branches converge on the same new key.
Global Changes
This table lists the general merge rules for keys.
| Local Branch | Remote Branch | Result |
|---|---|---|
| No change | Change | Keep Remote |
| Change | No Change | Keep Local |
| Same change | Same change | Keep |
| Change key | Change same key value to different than Local | Conflict |
Change Conflict Conditions
These change combinations result in merge conflicts.
- Both branches add the same key with different field values.
- Both branches modify the same object differently.
- One branch modifies a key while the other deletes it.
- Both branches rename the same key differently.
- Both branches independently add the same key with incompatible definitions.
Change Types
This section lists and describes the types of object-level changes evaluated by the merge.
- Addition: Local or Remote branch adds new object. Object in Base.
- Deletion: Local or Remote branch removes object. Object present in Base.
- Modification: Local or Remote branch changes object's non-key property. Object's non-key property differs from Base.
- Reorder: Local or Remote branch changes sequence of objects. Objects and order present in Base.
- Rename: Local or Remote branch changes a key identifier. Change treated as a deletion plus addition. Key identifier present in Base.
Complete List of Changes and Merge Rules
This table lists and explains Semantic Modeler's merge for keys.
| Local Modification | Remote Modification | Rule (Natural Language) | Result |
|---|---|---|---|
| No change | No change | No change made in either branch. No change in merge result. | No action |
| No change | Addition | Remote branch adds object with unique key. Merge results include new object. | Addition kept |
| No change | Modification | Remote branch modifies an existing object's properties. Merge results include modified object's properties. | Modification kept |
| No change | Deletion | Remote branch deletes an object. Merge results reflect object deletion. | Deletion kept |
| Addition | No change | Local branch adds object with unique key. Merge results include new object. | Addition kept |
| Addition | Addition (same object) | Local and Remote branches add the same object with identical fields and values. Merge results keep only one instance of the object. | Addition kept |
| Addition | Addition (different object) | Local and Remote branches add different objects with distinct unique keys. Merge results include all objects. | Additions merged |
| Addition | Addition (same key, different fields) | Local and Remote branches add object with the same unique key but different fields and values. Results in merge conflict that user must resolve. | Merge conflict |
| Modification | No change | Local branch modifies the properties of an existing object. Merge results include the modified object. | Modification kept |
| Modification | Modification (same change) | Local and Remote branches make the same change to an existing object. Merge results include the modified object. | Modification kept |
| Modification | Modification (different change) | Local and Remote branches make different changes to the same object's property or field. Results in merge conflict that user must resolve. | Merge conflict |
| Modification | Deletion | Local branch modified an existing object and Remote branch deletes the same existing object. Results in merge conflict that user must resolve. | Merge conflict |
| Deletion | No change | Local branch deletes an object. Merge results remove the object. | Deletion kept |
| Deletion | Deletion (same object) | Local and Remote branches delete the same object. Merge results deletes the object. | Deletion kept |
| Deletion | Delection (different object) | Local branch deletes an existing object and Remote branch deletes a different object. Merge results deletes both objects. | Deletions merged |
| Deletion | Modification | Local branch deletes an existing object and Remote branch modifies the same existing object. Results in merge conflict that user must resolve. | Merge conflict |
| No change | Reorder | Remote branch reorders objects. Merge results contains reordered objects. | Remote order kept |
| Reorder | No change | Local branch reorders objects. Merge results contains reordered objects. | Local order kept |
| Reorder | Reorder | Local branch and Remote branch reorder the same objects. Merge results contains the Local branch's order. | Local order kept |
| Rename | No change | Local branch renames an existing object (identifier changed). Merge results display both old and new versions for manual review. | Both kept |
| No change | Rename | Remote branch renames an existing object (identifier changed). Merge results contain both old and new versions for manual review. | Both kept |
| Rename | Rename (same key) | Local branch and Remote branch rename same existing object to the same name (new identifier). Merge results contain one instance of the new name. | Rename kept |
| Rename | Rename (different keys) | Local branch and Remote branch rename the same existing object to different names (new identifier). Merge results contain both old and new identifiers and require manual review. | Both kept |