Knowledge graph sync behaviors for attribute filtered replicas

This blog article describes scenarios in which the synchronize delta download behavior for attribute filtered replicas may appear in unexpected ways. Attribute filters in knowledge graph replicas are in preview at 12.1 due to these behaviors.

Problem

When synchronizing an ArcGIS Knowledge replica using delta download, some edits may appear to be missing or returned in an unexpected form. For example, entities may not be returned as adds or deletes when they appear to move into or out of the replica definition, and related content such as relationships, provenance, or documents may not be included.

Cause

This behavior occurs because ArcGIS Knowledge synchronize delta download uses a change tracking model, not an archiving model. The service tracks what has changed since the last synchronization, but it does not store historical attribute membership or previous replica participation for entities, relationships, or related objects. As a result, the service cannot always infer whether an instance previously belonged to a replica when attribute filters are used.

Workaround

If a complete and current representation of the replica data is required, particularly after encountering any of the edge cases described below, create or refresh the replica using a snapshot. A snapshot download materializes the full replica contents and avoids ambiguity introduced by change tracking semantics.

The following guide can help you choose between snapshot or delta download when synchronizing an ArcGIS Knowledge replica.

Use delta download in the following scenarios:

• You expect incremental changes and are comfortable with change tracking semantics.
• Attribute‑filtered replicas are stable, and entities are not frequently moving into or out of the replica definition.
• Missing adds or deletes due to update‑in or update‑out scenarios are acceptable.

Use a snapshot in the following scenarios:

• You need a complete and authoritative representation of the replica data.
• Entities, relationships, provenance, or documents may have moved into or out of the replica definition since the last synchronization.
• You encounter any of the edge cases described in this article and require the replica to be fully reconciled.

Snapshot downloads materialize the full replica contents and avoid ambiguity introduced by change tracking, attribute filters, and historical membership limitations.

Entity behavior

add: { entity }

upd: { entity }

upd: { entity }

del: { entity }

 The following explanations provide further context related to entity behaviors.

• When updating an entity moving into the replica, the entity is returned as an update, not an add. Since the system does not track historical replica membership, it cannot determine whether the entity previously belonged to the replica. This behavior matches ArcGIS Online synchronize semantics.
• When updating an entity moving out of a replica, no delete is returned. This is because the service cannot infer that the entity should be deleted from the replica because historical attribution is not stored.

Relationship behavior

Relationships participate in a replica only when both endpoints participate in the replica definition.

add: { relationship }

upd: { entity }

del: { relationship }

 The following explanations provide further context related to relationship behaviors.

• Adding a relationship where only one endpoint is in the replica will result in the relationship not being returned in the delta download. As a result, the relationship does not exist in the replica because both endpoints are not included.
• Updating an entity out of a replica, the entity update is not reported due to change tracking semantics. Additionally, relationships are not returned because an endpoint no longer participates in the replica.
• The relationship connections are not included when an entity update moves into the replica.

Provenance behavior

Add: add: { provenance }

Update: upd: { provenance }

Delete: del: { provenance }

upd: { entity | relationship }

del: { provenance }

The following explanations provide further context related to provenance behaviors.

• A provenance delete may be returned when an entity or relationship moves into the replica, even if the replica never previously included that provenance, due to change tracking semantics.

• No results are returned when an entity or relationship moves out of the replica because the replica is unaware that the data no longer participates in the replica definition.

Source document behavior

add: { entity | relationship, provenance, source document }

upd: { entity | relationship }

upd: { provenance }

add: { source document }

del: { source document }

 The following explanations provide further context related to source document behaviors.

• When updating an entity or relationship, the provenance and source documents are not included because attribute history is not stored.
• Source documents are included when updating provenance to ensure the replica has complete information when provenance source types are updated.
• Deleting a source document does not validate or update provenance references. A provenance may reference a source document that no longer exists.

Connected documents (HasDocument relationships) behavior

add: { hasDocument, document }

upd: { entity }

del: { hasDocument }

del: { hasDocument, document }

The following explanations provide further context related to connected document behaviors.

• When adding a HasDocument relationship, the system cannot efficiently determine whether the document already exists elsewhere in the replica. As a result, duplicates may be returned. Clients should upsert documents into their replica.
• When updating an entity into the replica, the connected HasDocument relationships and documents are not included.
• Deleting a HasDocument relationship will not delete the destination document if it still exists in the service.

Additional Information

Similar synchronize semantics are used in ArcGIS Online. These behaviors are expected and occur due to the following factors:

• Change tracking–based synchronization
• Attribute‑filtered replica definitions
• Performance constraints when evaluating historical relationships