Update sequence number

A query or mutation can return the current USN by shaping the output data with the updateSequenceNumber field. This same value can be specified through the updateSequenceNumber argument to a new mutation and ensures that the server-side changes will only be saved if the USN matches. This is a way for a caller to ensure that they are always working with up-to-date values.

If null is passed as an updateSequenceNumber argument value, the server-side USN is ignored, and the changes can be saved, which allows a caller to follow a last-writer-wins model.

If the updateSequenceNumber argument is not specified at all, then it still is set to null when you save the changes to the server. When the GraphQL Server fetches an object from the Content Engine server before you update it (subject to some batching behavior, described later, where fetch-less instantiation might be used), the current USN is also fetched. However, there is a small window where another change might occur before saving the object. If the USN is not set to null, it might lead to some intermittent errors. If the caller wants to enforce a certain state of the object when making changes, it should specify a non-null updateSequenceNumber.

There are some further conditions when dealing with lists of dependent objects where the USN may still be used from a fetched object. This is described in a later section with details about dependent object list editing.