Immutable reference attributes

Learn about immutable reference attributes and when they come in to play.

Immutable vs. mutable – Let’s be clear

In object-oriented and functional programming, you need to keep in mind that an object is only changeable under certain conditions.
  • Immutable -- In object-oriented and functional programming, an immutable object is unchangeable; it’s an object whose state can’t be modified after it’s created
  • Mutable -- In contrast to a immutable object, a mutable object is changeable and can be modified after it’s created.

Why does immutability matter?

You’ll want to enable the immutability of reference attributes in certain cases to avoid a change in the referenced entities and avoid generating multiple events due to non-significant differences in the source data.

Consider this example...

The reference attribute of an entity, say entity A, is a link to a part of the attributes of the referenced entity, entity B, and the relationship that connects these entities. If the values of these linked attributes in the entity B or the relation changes, then the entity A with the reference attribute also changes. Often, several entities are linked with the same referenced entity via the referenced attribute.

To take that further, there’s an entity of the type Individual with an Address reference attribute and with Location type for the referenced entity. It is possible for multiple Individual entities, such as A1, A2, A3, and A4, to have the same address. This means that their Address reference attribute points to the same Location entity. If the Location entity has changed, then all reference attributes of the entities A1, A2, A3, and A4 change too. So the Reltio Platform generates an ENTITY_CHANGED event for all these entities to propagate the changes to the search system, history, and matching system. If the same address is used for four entities: A1, A2, A3, and A4, these get defined in the source system with some non-significant differences:
  • A1: New York, Main Avenue 123
  • A2: New York, Main Ave. 123
  • A3: New York, NY, Main Avenue, 123
  • A4: New York, Main Avenue 123
Logically, since all the addresses are the same, they match the same Location entity after cleansing and matching. So when the Reltio software loads the entities into the platform, this happens:
  1. Entity A1 loads, the software creates a Location entity B with the address New York, Main Avenue 123, and then generates an ENTITY_CREATED event for entity A1 and entity B.
  2. Entity A2 loads, and since the address is the same, the software uses Location entity B as the referenced entity in the Address reference attribute, but the attributes of the Location entity change to New York, Main Ave. 123. As a result, the software generates an ENTITY_CREATED event for entity A2, and then generates an ENTITY_CHANGED event for entity A1 (because the reference attribute has changed) and for entity B.
  3. Entity A3 loads, and since the address is the same, the software uses the Location entity B as the referenced entity in the Address reference attribute, but the attributes of the Location entity change to New York, NY, Main Avenue, 123. As a result, the software generates an ENTITY_CREATED event for entity A3, and then generates an ENTITY_CHANGED event for entities A1 and A2 (because the reference attribute has changed) and for entity B.
  4. Entity A4 loads and the software uses the Location entity B as the referenced entity in the Address reference attribute. The final attribute values of the Location entity depend on the order in which the entities are loaded. In this example, the software loaded entity A4 last, so the location is the same as for entity A1.

How can I control the situation?

The above example demonstrates how minor, non-significant differences in the source data produces multiple unnecessary events. The results still display as if the Location entity were not changed at all. Using the immutable reference attributes feature enables you to ignore such differences and not generate unnecessary events, which improves the performance and stability. The order of loading entities, which is random, determines the result.
  • If you enable the feature and then load the data, as described in the example, the software only generates one event, ENTITY_CREATED for each entity.
  • If you don’t enable the feature, you always have values for the Location entity, which was loaded first, as opposed to values for the Location entity, which was loaded last.

Important facts about using immutable reference attributes!

Consider these facts:
  • Reltio recommends that you always enable the immutability of reference attributes when you use Location as the reference attribute.
  • The immutability of reference attributes only affects changes done through the reference attributes. If you update the referenced entity directly; that is, not as a part of the reference attribute of another entity, then the software always applies the changes, and all events are generated.
  • Changes are ignored only for attributes of the referenced entity, not for attributes of the relation. They update as expected.
  • If a new source data; that is, another crosswalk type or value, which does not exist in the referenced entity loads, then it’s added and the referenced entity updates as expected (with disabled immutable reference attributes).
  • If the entity with the reference attribute is updated, and the referenced entity in the new reference attribute does not match the current referenced entity, then two things can happen:
    • A new referenced entity is created.
    • The referenced attribute points to the existing entity, which matches the incoming data; that is, the reference attribute changes.

To learn which reference attribute properties you can use, see Metadata reference attribute properties.