Object Storage

Object Storage allows you to store data as a KiiObject in a Bucket.

This page digs into more details about this feature. For the basic overview, please refer Mobile Features.

In a KiiObject, you can store key-value pairs and an Object Body (file). The main component of a KiiObject is key-value pairs. When you need an Object Body, you will handle it separately from the key-value pairs, using the SDK's uploading and downloading features.

A KiiObject can only have key-value pairs or an Object Body. For example, an object representing configuration setting typically does not need any Object Body, so you can create such a KiiObject with key-value pairs only. You can also have a KiiObject with an Object Body without any key-value pair (in this case, the SDK will insert some predefined key-value pairs in the object as described in the next section).

Key-Value Pairs

A key-value pair in Kii Cloud is just like any other associative array. An object can have multiple pairs of key and value, and the value can be fetched using the corresponding key. Kii Cloud stores the key-value pairs in a form of JSON.

There are two types of keys: predefined and custom.

Predefined keys

The predefined keys are the ones Kii Cloud reserve. All keys starting with "_" (underscore) are predefined keys. Kii Cloud does not allow your application to use these keys as custom keys.

The predefined keys listed in the following table will be updated automatically when an object is created and modified.

Name of the key Meaning of the value
_id The identifier of the object (Object ID). It is either assigned automatically by Kii Cloud or specified upon the object creation. The ID is unique in the bucket it belongs. Please read "Object ID and URI" (Android, iOS, JavaScript, Unity) for more details.
_owner The identifier of the user who created the object (User ID). This is used when specifying Object Access Control.
_created The object's created time in UNIX time (msec) in UTC.
_modified The object's last modified time in UNIX time (msec) in UTC. This value will be the same with _created if the object is newly-created.
_dataType The object's data type. If you explicitly set the data type when you create the object, this value will be preserved.
_bodyType The object body's data type. The data type you've set when you upload the object body will be preserved.
_version The object's version number. The initial value right after the object creation is 1. The value will be incremented as the object is updated. The value is used to realize the optimistic locking feature.

Custom keys

The custom keys are what your application can freely use. As long as your key name does not start with "_" (underscore), you can set any key-value pairs in an Object.

The values can be any of the following JSON-encodable types:

  • String
  • Boolean
  • Int
  • Long
  • Double
  • Byte Array
  • JSON
  • JSON Array
  • GeoPoint (geolocation)

For most cases, you will specify the same data type when you set a value and when you get the value. For more information on what will happen when you are passing values between multiple platforms or when you do some data type casting, please consult Key-Value Data Conversion.

When key-value pairs are stored in Kii Cloud, the corresponding indexes (for the buckets, keys, and values) are automatically generated on the server. The indexes are used for querying the objects.

Please note that the indexes will be generated only if the key length is up to 250 characters and the key value is up to 190 characters (for the string value). If an object has longer key/value length, the index for the object will not be generated; the object will not match with any query using this key.

Object Body

You can manage large data such as a file by associating it with a KiiObject. This large data is called the object body.

For example, you can store the metadata of a movie as key-value pairs in a KiiObject while uploading the movie file as the object body of the KiiObject.

Some of the Kii Cloud SDKs do not support manipulating the object body but you can update key-value pairs of a KiiObject that has the object body with those Kii Cloud SDKs. In that case, the object body remains unchanged.

Since the object body is usually big, the SDK handles it in the following way:

  • The API treats the key-value pairs and the object body separately although they are bound to a single KiiObject.

    • The client SDK reads and writes the object body as a file only when the object body is requested.
    • For the REST API, we provide the separate APIs for handling key-value pairs and for handling the object body.
  • Some client SDKs support suspending and resuming a file transfer. You can suspend a transfer of a large file and resume it later.

One KiiObject has one object body. You cannot store multiple object bodies in one KiiObject.

If you want to store multiple icons in one KiiObject, you can store them as key-value pairs by converting them to BASE64 data. In this case, you will get an error if the size of the key-value pairs expressed in the JSON format exceeds 64 KB. If the data size doesn't exceed the limit, this method has an advantage of letting you querying BASE64 and other data at once.