Setting a Key-value Pair

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

Specify a key-value pair as arguments of the setObject(_:forKey:) 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.

Swift:

let object = bucket.createObject()
object.setObject(NSNumber(integerLiteral: 987), forKey: "score")
object.setObject("easy", forKey: "mode")
object.setObject(NSNumber(booleanLiteral: false), forKey: "premiumUser")

Objective-C:

KiiObject *object = [bucket createObject];
[object setObject:[NSNumber numberWithInt:987]
           forKey:@"score"];
[object setObject:@"easy"
           forKey:@"mode"];
[object setObject:[NSNumber numberWithBool:NO]
           forKey:@"premiumUser"];

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 NSString, NSNumber, NSArray, and NSDictionary for setting a value with the setObject(_:forKey:) method.

Kii Cloud does not have any limitation to the ranges of stored values and can store the maximum values for the data types supported by NSNumber. The following table includes a subset of supported data types by NSNumber. You can use the other data types such as Int16 and Float.

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.

Swift:

Data type Method call Stored key-value pair in the JSON format Notes
NSString object.setObject("123", forKey: "data"); "data":"123"
NSNumber(Int) object.setObject(NSNumber(integerLiteral: 123), forKey: "data"); "data":123
NSNumber(Int64) object.setObject(NSNumber(value: 123 as Int64), forKey: "data"); "data":123
NSNumber(Double) object.setObject(NSNumber(floatLiteral: 123.456), forKey: "data"); "data":123.456
NSNumber(Bool) object.setObject(NSNumber(booleanLiteral: true), forKey: "data"); "data":true True or false is set because the NSNumber is set as a Bool.
KiiGeoPoint object.setGeoPoint(geoPoint, forKey: "data"); "data":{
"_type": "point",
"lat": 35.658603,
"lon": 139.745433
}		 geoPoint is (35.658603, 139.745433)
NSArray object.setObject(array, forKey: "data"); "data":[1,2,3] array is [1,2,3]
NSDictionary object.setObject(json, forKey: "data"); "data":{"a":"b"} json is {"a":"b"}

Objective-C:

Data type Method call Stored key-value pair in the JSON format Notes
NSString [object setObject:@"123" forKey:@"data"]; "data":"123"
NSNumber(int) [object setObject:[NSNumber numberWithInt:123] forKey:@"data"]; "data":123
NSNumber(long long) [object setObject:[NSNumber numberWithLongLong:123] forKey:@"data"]; "data":123
NSNumber(double) [object setObject:[NSNumber numberWithDouble:123.456] forKey:@"data"]; "data":123.456
NSNumber(BOOL) [object setObject:[NSNumber numberWithBool:YES] forKey:@"data"]; "data":true True or false is set because the NSNumber is set as a Bool.
KiiGeoPoint [object setGeoPoint:geoPoint forKey:@"data"]; "data":{
"_type": "point",
"lat": 35.658603,
"lon": 139.745433
}		 geoPoint is (35.658603, 139.745433)
NSArray [object setObject:array forKey:@"data"]; "data":[1,2,3] array is [1,2,3]
NSDictionary [object setObject:json forKey:@"data"]; "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 (NSDate) by storing the number of milliseconds since 00:00:00 UTC, Thursday, 1 January 1970. To do so, multiply a Double value in the timeIntervalSince1970 property by 1000.
  • Unlike the Android SDK, the iOS 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 NSString, Int, Double, and Bool 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.

Swift:

  • // Create a KiiObject.
let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
let object = bucket.createObject()

// Set key-value pairs.
object.setObject("my value", forKey: "stringValue")
object.setObject(NSNumber(integerLiteral: 123), forKey: "intValue")
object.setObject(NSNumber(value: UInt64(Date().timeIntervalSince1970 * 1000)), forKey: "longValue")
object.setObject(NSNumber(floatLiteral: 987.654), forKey: "doubleValue")
object.setObject(NSNumber(booleanLiteral: true), forKey: "booleanValue")

do{
  // Save the KiiObject.
  try object.saveSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}
  • // Create a KiiObject.
let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
let object = bucket.createObject()

// Set key-value pairs.
object.setObject("my value", forKey: "stringValue")
object.setObject(NSNumber(integerLiteral: 123), forKey: "intValue")
object.setObject(NSNumber(value: UInt64(Date().timeIntervalSince1970 * 1000)), forKey: "longValue")
object.setObject(NSNumber(floatLiteral: 987.654), forKey: "doubleValue")
object.setObject(NSNumber(booleanLiteral: true), forKey: "booleanValue")

// Save the KiiObject.
object.save { (object : KiiObject?, error : Error?) -> Void in
  if (error != nil) {
    // Handle the error.
    return
  }
}

Objective-C:

  • NSError *error = nil;

// Create a KiiObject.
KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
KiiObject *object = [bucket createObject];

// Set key-value pairs.
[object setObject:@"my value"
           forKey:@"stringValue"];
[object setObject:[NSNumber numberWithInt:123]
           forKey:@"intValue"];
[object setObject:[NSNumber numberWithLongLong:(long long)([[NSDate date] timeIntervalSince1970] * 1000)]
           forKey:@"longValue"];
[object setObject:[NSNumber numberWithDouble:987.654]
           forKey:@"doubleValue"];
[object setObject:[NSNumber numberWithBool:YES]
           forKey:@"booleanValue"];

// Save the KiiObject.
[object saveSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}
  • // Create a KiiObject.
KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
KiiObject *object = [bucket createObject];

// Set key-value pairs.
[object setObject:@"my value"
           forKey:@"stringValue"];
[object setObject:[NSNumber numberWithInt:123]
           forKey:@"intValue"];
[object setObject:[NSNumber numberWithLongLong:(long long)([[NSDate date] timeIntervalSince1970] * 1000)]
           forKey:@"longValue"];
[object setObject:[NSNumber numberWithDouble:987.654]
           forKey:@"doubleValue"];
[object setObject:[NSNumber numberWithBool:YES]
           forKey:@"booleanValue"];

// Save the KiiObject.
[object saveWithBlock:^(KiiObject *object, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }
}];

The above sample code creates a KiiObject with the following JSON format data (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 KiiGeoPoint object as its value in the KiiObject with the setGeoPoint(_:forKey:) 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.

Swift:

  • // Create a KiiObject.
let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
let object = bucket.createObject()

// Create GeoPoint objects.
let point1 = KiiGeoPoint(latitude: 35.658603, andLongitude: 139.745433)
let point2 = KiiGeoPoint(latitude: 35.658625, andLongitude: 139.745415)

// Set the GeoPoints to the KiiObject.
object.setGeoPoint(point1, forKey:"location1")
object.setGeoPoint(point2, forKey:"location2")

do{
  // Save the KiiObject.
  try object.saveSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}
  • // Create a KiiObject.
let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
let object = bucket.createObject()

// Create GeoPoint objects.
let point1 = KiiGeoPoint(latitude: 35.658603, andLongitude: 139.745433)
let point2 = KiiGeoPoint(latitude: 35.658625, andLongitude: 139.745415)

// Set the GeoPoints to the KiiObject.
object.setGeoPoint(point1, forKey:"location1")
object.setGeoPoint(point2, forKey:"location2")

// Save the KiiObject.
object.save { (object : KiiObject?, error : Error?) -> Void in
  if (error != nil) {
    // Handle the error.
    return
  }
}

Objective-C:

  • NSError *error = nil;

// Create a KiiObject.
KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
KiiObject *object = [bucket createObject];

// Create GeoPoint objects.
KiiGeoPoint *point1 = [[KiiGeoPoint alloc] initWithLatitude:35.658603
                                               andLongitude:139.745433];
KiiGeoPoint *point2 = [[KiiGeoPoint alloc] initWithLatitude:35.658625
                                               andLongitude:139.745415];

// Set the GeoPoints to the KiiObject.
if (point1) {
  [object setGeoPoint:point1
               forKey:@"location1"];
}
if (point2) {
  [object setGeoPoint:point2
               forKey:@"location2"];
}

// Save the KiiObject.
[object saveSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}
  • // Create a KiiObject.
KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
KiiObject *object = [bucket createObject];

// Create GeoPoint objects.
KiiGeoPoint *point1 = [[KiiGeoPoint alloc] initWithLatitude:35.658603
                                               andLongitude:139.745433];
KiiGeoPoint *point2 = [[KiiGeoPoint alloc] initWithLatitude:35.658625
                                               andLongitude:139.745415];

// Set the GeoPoints to the KiiObject.
if (point1) {
  [object setGeoPoint:point1
               forKey:@"location1"];
}
if (point2) {
  [object setGeoPoint:point2
               forKey:@"location2"];
}

// Save the KiiObject.
[object saveWithBlock:^(KiiObject *object, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }
}];

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 byte array, a JSON object, and an array of JSON objects. They correspond to the NSDictionary and NSArray, respectively.

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

Swift:

  • // Create a KiiObject.
let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
let object = bucket.createObject()

// Set a value of a JSON object.
let jsonObject: Dictionary = ["score": 987, "mode": "easy"] as [String : Any]
object.setObject(jsonObject, forKey: "myObject")

// Set a value of a JSON array.
let arrayElement1: Dictionary = ["Name": "Alice", "age": 30] as [String : Any]
let arrayElement2: Dictionary = ["Name": "Bob", "age": 28] as [String : Any]
let jsonArray = [arrayElement1, arrayElement2]
object.setObject(jsonArray, forKey: "myArray")

do{
  // Save the KiiObject.
  try object.saveSynchronous()
} catch let error as NSError {
  // Handle the error.
  return
}
  • // Create a KiiObject.
let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
let object = bucket.createObject()

// Set a value of a JSON object.
let jsonObject: Dictionary = ["score": 987, "mode": "easy"] as [String : Any]
object.setObject(jsonObject, forKey: "myObject")

// Set a value of a JSON array.
let arrayElement1: Dictionary = ["Name": "Alice", "age": 30] as [String : Any]
let arrayElement2: Dictionary = ["Name": "Bob", "age": 28] as [String : Any]
let jsonArray = [arrayElement1, arrayElement2]
object.setObject(jsonArray, forKey: "myArray")

// Save the KiiObject.
object.save { (object : KiiObject?, error : Error?) -> Void in
  if (error != nil) {
    // Handle the error.
    return
  }
}

Objective-C:

  • NSError *error = nil;

// Create a KiiObject.
KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
KiiObject *object = [bucket createObject];

// Set a value of a JSON object.
NSDictionary* jsonObject = @{@"score":@987, @"mode":@"easy"};
[object setObject:jsonObject
           forKey:@"myObject"];

// Set a value of a JSON array.
NSDictionary* arrayElement1 = @{@"Name":@"Alice", @"age":@30};
NSDictionary* arrayElement2 = @{@"Name":@"Bob", @"age":@28};
NSArray* jsonArray = @[arrayElement1, arrayElement2];
[object setObject:jsonArray
           forKey:@"myArray"];

// Save the KiiObject.
[object saveSynchronous:&error];
if (error != nil) {
  // Handle the error.
  return;
}
  • // Create a KiiObject.
KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
KiiObject *object = [bucket createObject];

// Set a value of a JSON object.
NSDictionary* jsonObject = @{@"score":@987, @"mode":@"easy"};
[object setObject:jsonObject
           forKey:@"myObject"];

// Set a value of a JSON array.
NSDictionary* arrayElement1 = @{@"Name":@"Alice", @"age":@30};
NSDictionary* arrayElement2 = @{@"Name":@"Bob", @"age":@28};
NSArray* jsonArray = @[arrayElement1, arrayElement2];
[object setObject:jsonArray
           forKey:@"myArray"];

// Save the KiiObject.
[object saveWithBlock:^(KiiObject *object, NSError *error) {
  if (error != nil) {
    // Handle the error.
    return;
  }
}];

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"
  }
}