Setting a Key-value Pair

In order to set a key-value pair in a KiiObject, call the set() method of the KiiObject class. The set() method has an overloaded version for each data type.

Specify a key-value pair as arguments of the set() method. The specified key-value pair will be saved at the first level of the JSON document hierarchy.

The following sample code illustrates how to set key-value pairs. For sample code that includes a step to save a KiiObject, see Creating a KiiObject or Setting a value of a basic data type below. See also Updating a KiiObject for setting key-value pairs.

var object = bucket.createObject();
obj.set("score", 987);
obj.set("mode", "easy");
obj.set("premiumUser", false);

Data in the JSON format will be created as below after executing the above code and saving the KiiObject (Predefined fields are omitted).

{
  "score": 987,
  "premiumUser": false,
  "mode": "easy"
}

In order to set a key-value pair at the second or subsequent level, prepare a JSON object that has the key-value pair at the desired level and set the JSON object at the first level.

The maximum size of a KiiObject is 65534 characters (the total size of key-value pairs in the JSON format, including some internal fields used by Kii Cloud).

Supported data types

You can use any of the following data types for setting a value with the set() method.

Kii Cloud does not have any limitation to the ranges of stored values and can store the maximum values for the supported data types.

Use the values in the "Stored key-value pair in the JSON format" column in the following table as reference when checking data in the data browser in the developer portal and referencing data from another platform. You do not need to pay attention to the JSON format if you to use the same data type for writing and reading a key-value pair.

Data type Method call Stored key-value pair in the JSON format Notes
string set("data", "123"); "data":"123"
number set("data", 123); "data":123
boolean set("data", true); "data":true
KiiGeoPoint set("data", geoPoint); "data":{
"_type": "point",
"lat": 35.658603,
"lon": 139.745433
}		 geoPoint is (35.658603, 139.745433)
array set("data", array); "data":[1,2,3] array is [1,2,3]
object set("data", json); "data":{"a":"b"} json is {"a":"b"}
  • You cannot set a null value. An attempt to set a null value will be ignored or cause an error.
  • You can easily handle a date value (Date) by storing the number of milliseconds since 00:00:00 UTC, Thursday, 1 January 1970. To do so, use the valueOf() method to convert the date value to a number value.
  • Unlike the Android SDK, the JavaScript SDK does not support the feature to encode a byte array as BASE64.

Setting a value of a basic data type

The following sample code illustrates how to set string, number, and boolean values when a KiiObject is created.

This is based on the sample code in Creating a KiiObject. The code block for setting values is different.

  • // Create a KiiObject.
var obj = KiiUser.getCurrentUser().bucketWithName("MyBucket").createObject();

// Set key-value pairs.
obj.set("stringValue", "my value");
obj.set("intValue", 123);
obj.set("longValue", new Date().valueOf());
obj.set("doubleValue", 987.654);
obj.set("booleanValue", true);

// Save the KiiObject.
obj.save().then(
  function(theObject) {
    // Do something.
  }
).catch(
  function(error) {
    var theObject = error.target;
    var errorString = error.message;
    // Handle the error.
  }
);
  • // Create a KiiObject.
var obj = KiiUser.getCurrentUser().bucketWithName("MyBucket").createObject();

// Set key-value pairs.
obj.set("stringValue", "my value");
obj.set("intValue", 123);
obj.set("longValue", new Date().valueOf());
obj.set("doubleValue", 987.654);
obj.set("booleanValue", true);

// Save the KiiObject.
obj.save({
  success: function(theObject) {
    // Do something.
  },
  failure: function(theObject, errorString) {
    // Handle the error.
  }
});

This sample code will create a JSON format data like the following (the predefined fields are omitted):

{
  "stringValue": "my value",
  "booleanValue": true,
  "longValue": 1495677489018,
  "doubleValue": 987.654,
  "intValue": 123
}

Setting a geolocation

This section explains how to set a geolocation (KiiGeoPint) in a KiiObject.

First, create a KiiGeoPoint object by passing a latitude and a longitude. Then, set a key-value pair that has the created KiiGeoPoint object as its value in the KiiObject with the setGeoPoint() method.

The following sample code illustrates how to create a KiiObject in "MyBucket", a bucket in the currently logged-in user's scope, and set two geolocations in the KiiObject.

  • // Create a KiiObject.
var obj = KiiUser.getCurrentUser().bucketWithName("MyBucket").createObject();

// Create GeoPoint objects.
var point1 = KiiGeoPoint.geoPoint(35.658603, 139.745433);
var point2 = KiiGeoPoint.geoPoint(35.658625, 139.745415);

// Set the GeoPoints to the KiiObject.
obj.setGeoPoint("location1",point1);
obj.setGeoPoint("location2",point2);

// Save the KiiObject.
obj.save().then(
  function(theObject) {
    // Do something.
  }
).catch(
  function(error) {
    var theObject = error.target;
    var errorString = error.message;
    // Handle the error.
  }
);
  • // Create a KiiObject.
var obj = KiiUser.getCurrentUser().bucketWithName("MyBucket").createObject();

// Create GeoPoint objects.
var point1 = KiiGeoPoint.geoPoint(35.658603, 139.745433);
var point2 = KiiGeoPoint.geoPoint(35.658625, 139.745415);

// Set the GeoPoints to the KiiObject.
obj.setGeoPoint("location1",point1);
obj.setGeoPoint("location2",point2);

// Save the KiiObject.
obj.save({
  success: function(theObject) {
    // Do something.
  },
  failure: function(theObject, errorString) {
    // Handle the error.
  }
});

Make sure to call the save() method. The key-value pairs set in the KiiObject are not saved on Kii Cloud until the method is called.

Setting complex data

In addition to the basic data types, the SDK supports a JSON object and an array of JSON objects.

The following sample code illustrates how to set values of these data types.

  • // Create a KiiObject.
var obj = KiiUser.getCurrentUser().bucketWithName("MyBucket").createObject();

// Set a value of a JSON object.
obj.set("myObject", {"score": 987, "mode": "easy"});

// Set a value of a JSON array.
obj.set("myArray", [{"Name": "Alice", "age": 30},
                    {"Name": "Bob", "age": 28}]);

// Save the KiiObject.
obj.save().then(
  function(theObject) {
    // Do something.
  }
).catch(
  function(error) {
    var theObject = error.target;
    var errorString = error.message;
    // Handle the error.
  }
);
  • // Create a KiiObject.
var obj = KiiUser.getCurrentUser().bucketWithName("MyBucket").createObject();

// Set a value of a JSON object.
obj.set("myObject", {"score": 987, "mode": "easy"});

// Set a value of a JSON array.
obj.set("myArray", [{"Name": "Alice", "age": 30},
                    {"Name": "Bob", "age": 28}]);

// Save the KiiObject.
obj.save({
  success: function(theObject) {
    // Do something.
  },
  failure: function(error) {
    var theObject = error.target;
    var errorString = error.message;
    // Handle the error.
  }
});

Make sure to call the save() method. The key-value pairs set in the KiiObject are not saved on Kii Cloud until the method is called.

The above sample code creates a KiiObject with the following JSON format data (Predefined fields are omitted).

{
  "myArray": [
    {
      "Name": "Alice",
      "age": 30
    },
    {
      "Name": "Bob",
      "age": 28
    }
  ],
  "myObject": {
    "score": 987,
    "mode": "easy"
  }
}