Updating a KiiObject

Kii Cloud provides the following two options for updating a KiiObject:

Update a KiiObject fully or partially.
Enable or disable the overwrite check.

You can specify these options when you update a KiiObject. Note that one of the combinations offers little benefits when using with the Kii Cloud SDK. For more information, see Combinations of updating options below.

To safely update a KiiObject, you might need to consider errors that can happen while multiple KiiObjects are being updated. For more information, see Transactions.

Full update versus partial update

This option determines how Kii Cloud updates existing key-value pairs on the server with key-value pairs that are sent from the client. The full update completely overwrites a KiiObject on the server with key-value pairs from the client while the partial update merges key-value pairs from the client to a KiiObject on the server.

Full update

This update completely overwrites a KiiObject.

All the key-value pairs previously stored in the KiiObject will be discarded, and newly-specified key-value pairs will be stored.

Partial update

This update partially updates a KiiObject.

Only the key-value pairs from the client will be updated. All the other key-value pairs in the KiiObject will be preserved.

Note that you cannot delete the existing keys with the partial update. Use the full update to delete keys.

The JSON document in this example has a hierarchy of just one level. If your JSON document has a hierarchy of multiple levels, the fields on the second and subsequent levels from the client are also merged and saved on the server with no problem.

Overwrite check

The overwrite check feature allows you to use a technique known as optimistic locking.

This feature checks if a KiiObject on Kii Cloud has been modified or the modified time has been changed since the KiiObject was downloaded to the client. If it has been modified, an error is returned. The feature prevents possible data loss in a KiiObject when it is modified simultaneously from multiple clients.

Although Kii Cloud does not provide any exclusive locking feature that is often used in typical databases, you can prevent data conflicts by leveraging this check feature.

Example of optimistic locking

Suppose that there is a bucket in the application scope for storing the game's high score. This bucket has one KiiObject that clients update when they hit the highest score. The basic logic should be as follows.

Get the KiiObject for the high score from Kii Cloud.
Compare the latest game score with the value of the highscore key in the obtained KiiObject, and update the KiiObject with the latest game score if it is higher than the existing high score.

Now suppose Client A and Client B finish the game simultaneously, and they get the scores of 87 and 76, respectively. If the existing high score is 60, the high score should be updated to 87.

The update sequence is as follows:

Client A gets the existing high score (highscore = 60).
Client B gets the existing high score (highscore = 60).
Client A locally sets the new high score (highscore = 87).
Client B locally sets the new high score (highscore = 76).
Client A updates the high score on Kii Cloud (highscore = 87).
Client B updates the high score on Kii Cloud (highscore = 76).

Without the overwrite check: The KiiObject will be unconditionally updated, so it will be updated with the latest score 76. The update by Client A will be lost and the new high score will be invalid.

With the overwrite check: Client B will get an error when it attempts to update the KiiObject because the value of _version on the client (1) and that on the Kii Cloud (2) are different. Client B can retry the update by repeating the process from Step 2.

Note that this example is very simplified. When you develop a real mobile app, you would need to think about considerations in Security according to the importance of app data.

Consider the possibility of simultaneous updates and the importance of data integrity before you determine whether to use the overwrite check feature or not. The overwrite check allows your mobile app to avoid update conflicts, but it also requires error and retry handling. If you know that there will be no simultaneous updates or you can accept update conflicts, you might consider disabling the feature.

Combinations of updating options

The following table summarizes the possible combinations of the updating options for the Kii Cloud SDK.

	Disabled overwrite check	Enabled overwrite check
Full update	Full Update without the Overwrite Check You do not need to refresh the KiiObject before updating it if the client has all the necessary key-value pairs for the KiiObject. All the key-value pairs on the server will be replaced with the ones sent from the client.	Full Update with the Overwrite Check You need to refresh the KiiObject before updating it because the latest value for the `_version` key is required. At the same time, all the existing key-value pairs will be downloaded. All the key-value pairs on the server will be replaced with the ones sent from the client.
Partial update	Partial Update without the Overwrite Check You should not refresh the KiiObject before updating it because you want to send only the changed key-value pairs to the server. The key-value pairs sent from the client are merged with the existing key-value pairs on the server.	Rarely used with the Kii Cloud SDK You need to refresh the KiiObject before updating it because the latest value for the `_version` key is required. At the same time, all the existing key-value pairs will be downloaded. All the key-value pairs are sent to the server unless you delete unchanged pairs explicitly. The result will be virtually the same as that of the full update.

As shown in the table above, the Kii Cloud SDK supports to update a KiiObject partially with the overwrite check enabled, but this combination has little meaning in most cases and it is not covered in this guide. If you update a KiiObject that way, you will need to perform special processing such as deleting downloaded key-value pairs and then updating the KiiObject.