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 Kii Cloud SDK Overview.

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 reserves for its internal usage. All predefined keys start with "_" (underscore), and Kii Cloud does not allow your application to use any key that starts with "_" to be used as a custom key.

Some examples of such predefined keys include:

  • The values for the internal data management such as _id and _version.
  • The auto-filled values such as _created (created time) and _modified (modified time) that you can extract with the SDK's dedicated methods.

For more information on the predefined keys, please refer to the detailed docs in References.

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 files (Object Body) while associating them with KiiObjects.

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

Since an Object Body is usually big, the SDK handles it like the followings:

  • The API treats the key-value pairs and an Object Body separately although they are both bound to the same KiiObject.

    • The client SDK reads and writes an 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 an Object Body.
  • Some client SDKs support to suspend and resume the file transfer. You can suspend a file transfer in the middle and later resume the transfer.

One KiiObject can store just 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.