Accessing a JSON Document
Fields in the JSON document in each KiiObject are set and obtained as key-value pairs.
Key-value pairs written by the Kii Cloud SDK are saved in the JSON format on Kii Cloud. Those key-value pairs set through the Kii Cloud SDK methods are saved at the first level of the JSON hierarchy. The Kii Cloud SDK reads the data in the first and subsequent levels as key-value pairs.
The REST APIs directly manage the JSON string as data in requests and responses.
For example, two clients that share data access key-value pairs in the JSON document as below. The same applies when a client that saved data reads it later.
Since KiiObjects are saved in the JSON format, Client 1 and Client 2 in the figure can correctly read values as far as the clients use the correct data type even if their OSes are different.
The values at the first level of the JSON hierarchy are automatically indexed. Because of this index, you can query KiiObjects that match your query conditions at high speed. Note that values at the second and subsequent levels cannot be queried.
Key-value pairs
You specify the key name to store and reference its value with the Kii Cloud SDK, as you would with a common associative memory.
There are two types of keys: predefined and custom.
Predefined keys
All the keys whose name starts with "_" (underscore) are predefined keys and reserved by Kii Cloud. You cannot use those keys as custom keys in your mobile app.
The value of the predefined keys in the following table is updated automatically when a KiiObject is created and modified.
| Key | Description |
|---|---|
| _id | The identifier of the KiiOject (KiiObject ID). It is either assigned automatically by Kii Cloud or specified on the mobile app upon the KiiObject creation. The ID is unique within the bucket for the KiiObject. |
| _owner | The identifier of the user who created the KiiObject (User ID). This is used when setting access control of the KiiObject. |
| _created | The created time of the KiiObject in UNIX time (msec) in UTC. |
| _modified | The last modified time of the KiiObject in UNIX time (msec) in UTC. The value of this key is the same as that of the _created key just after the KiiObject is created. |
| _dataType | The data type of the KiiObject. You can explicitly set the data type when you create a KiiObject. The data type is especially used when the object body is published. |
| _bodyType | The data type of the object body. You can explicitly set the body type when you upload an object body. |
| _version | The version number of the KiiObject. The initial value is 1 when a KiiObject is created. The value will be incremented as the KiiObject is updated. The value is used with the optimistic locking feature that detects update conflicts. |
Custom keys
You can create and use custom keys in your mobile app for any purposes. You can assign any name to a custom key with exceptions of reserved ones for the predefined keys.
You can use any data types that are compatible with JSON data types, such as JSON array and JSON object as well as integer and string. Geolocation is also defined as a data type.
When a key-value pair is stored in Kii Cloud, a corresponding index based on the bucket, key, and value is automatically generated on the server. The index is used for querying the KiiObject.
Note that an index is generated only if the key length is up to 250 characters and the key value is up to 190 characters (as a string value). Otherwise, no index is created and the key-value pair cannot be queried.