Understanding Delta Publish

When AMPS receives a delta publish request, AMPS first performs any preprocessing or enrichment specified for the incoming message. AMPS then fully parses both the incoming message and the destination message, and then merges the contents of the incoming update into the existing message. The mechanism that merges the messages is message-type independent, and does not rely on the syntax or semantics of any particular message type.

The message is merged before the message is persisted to the SOW, recorded in the transaction log, replicated, or delivered to subscribers.

Since delta publish uses a very simple, compact syntax -- a partial message -- for updates, AMPS makes certain assumptions about the intent of an update:

1. AMPS replaces the contents of the existing message based on the parsed identifiers in the update. An update to an anonymous element or the root level of a subdocument is a full replacement of that value.

   For example, consider the following JSON document:

   {"id":42, "contents":{"packages":[{"box":"chocolates"},
                                     {"bowl":"noodles"}]}}

   An update to the packages field of the document replaces the subdocument, so providing the following delta_publish:

   {"id":42, "contents":{"packages":[{"basket":"eggs"}]}}

   Replaces the previous value of packages, and produces the message:

   {"id":42, "contents":{"packages":[{"basket":"eggs"}]}}

2. A missing field in a delta publish means that the content of that field is unchanged.

   Since AMPS treats the absence of a field in a delta update to mean that the previous value is unchanged, a delta_publish cannot be used to remove fields from a document.

   For example, consider the following JSON document:

   {"id":42", "flowers":"roses"}

   A delta_publish that attempts to remove the flowers field by simply removing it will be treated as though there is no update to that field. In other words, a delta_publish of:

   {"id":42}

   will produce no change to the flowers field, and result in a document of:

   {"id":42, "flowers":"roses"}

   To remove a field from a message, republish the full message.

3. AMPS does not evaluate whether a field has a different value than the previous message or has a republish of the previous value when processing a delta_publish -- any field present in the delta publish will replace the corresponding field in the existing message.

   For example, consider an application that advertises whether a given system is accepting requests with messages along the lines of:

   {"systemId":"A34-Astro", "status":"available", "commandAccepted":["print","scan","fax"]}

   Now, the system sends a delta publish update that does not change the status:

   {"systemId":"A34-Astro", "status":"available"}

   Even though no value in the message has changed, the publish is still processed, and the publish will still be delivered to subscribers. The fact that it replaces an existing value with the same value does not matter for AMPS. This is still considered an update. (An individual subscriber can choose not to receive updates that do not change the value of a field by using the no_empties option with a delta subscription as described in the Receiving Only Updated Fields section.)

4. AMPS uses the fully parsed values of the existing message and the updated message to perform the merge. This means that nested elements are processed as described in Compound Types in AMPS.

   Use care when combining delta publish with nested elements, particularly nested elements within arrays or nested elements that contain arrays.