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.
- Uses the object's key and stable mapping information, when available, to identify a renamed object.
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.
- Both branches rename the same base object to different names.
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 contain renamed object. | Local rename kept |
| No change | Rename | Remote branch renames an existing object (identifier changed). Merge results contain renamed object. | Remote rename kept |
| Rename | Rename (same name) | Local branch and Remote branch rename same existing object to the same name (new identifier). Merge results contain the new name. | Rename kept |
| Rename | Rename (different name) | Local branch renames an existing object (new identifier) and Remote branch renames the same existing object (new identifier) to a different name. Results in merge conflict that the user must resolve. | Merge conflict * |
*Make renames in focused commits and avoid renaming the same object in multiple branches. If a rename conflict occurs, compare the Local and Remote definitions and keep the intended name and configuration. After resolving a column or join rename, verify its mappings and dependent objects.
Rename Detection for Common Objects
For key-based objects, the Semantic Modeler merge rules use the object's key and where applicable stable mapping information to identify the same base object after a rename. This allows the merge to distinguish a rename from two independent additions.
| Object | Matching and rename consideration |
|---|---|
| Physical column | The column name is the key. The parent physical table and unchanged column details can help identify a renamed column. If both branches rename the same column differently, the merge reports a conflict. |
| Physical joins | The join is identified by its target table and normalized join conditions. If both branches rename or otherwise change the same join so that they represent incompatible identities, the merge reports a conflict instead of creating two joins. |
| Initialization blocks | An initialization block is a named object. If both branches rename the same initialization block to different names, the merge reports a conflict instead of creating two blocks. |
For variables in an initialization block, the variables array is order-sensitive: for a global or session initialization-block query, result columns populate variables by list order.
Avoid reordering variables while another branch edits them. If both branches rename the same variable differently, the Semantic Modeler merge reports a conflict for manual resolution.