Creating a KiiObject

This topic explains how to create a KiiObject. For setting a JSON document in a KiiObject, see Setting a Key-value Pair.

Creating a KiiObject

In order to create a KiiObject, create a KiiObject on the client by calling the createObject() method of the destination bucket and then the save(_:) method. Kii Cloud automatically assigns the ID of the created KiiObject.

Swift:

  • let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
    
    // Create a KiiObject in the application-scope bucket.
    let object = bucket.createObject()
    
    // Set key-value pairs.
    object.setObject(NSNumber(value: 987 as Int32), forKey: "score")
    object.setObject("easy", forKey: "mode")
    object.setObject(NSNumber(value: false as Bool), forKey: "premiumUser")
    
    do{
      // Save the KiiObject.
      try object.saveSynchronous()
    } catch let error as NSError {
      // Handle the error.
      return
    }
  • let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
    
    // Create a KiiObject in the application-scope bucket.
    let object = bucket.createObject()
    
    // Set key-value pairs.
    object.setObject(NSNumber(value: 987 as Int32), forKey: "score")
    object.setObject("easy", forKey: "mode")
    object.setObject(NSNumber(value: false as Bool), forKey: "premiumUser")
    
    // Save the KiiObject.
    object.save { (object : KiiObject?, error : Error?) -> Void in
      if (error != nil) {
        // Handle the error.
        return
      }
    }

Objective-C:

  • KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
    NSError *error = nil;
    
    // Create a KiiObject.
    KiiObject *object = [bucket createObject];
    
    // Set key-value pairs.
    [object setObject:[NSNumber numberWithInt:987]
               forKey:@"score"];
    [object setObject:@"easy"
               forKey:@"mode"];
    [object setObject:[NSNumber numberWithBool:NO]
               forKey:@"premiumUser"];
    
    // Save the KiiObject.
    [object saveSynchronous:&error];
    if (error != nil) {
      // Handle the error.
      return;
    }
  • KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
    
    // Create a KiiObject.
    KiiObject *object = [bucket createObject];
    
    // Set key-value pairs.
    [object setObject:[NSNumber numberWithInt:987]
               forKey:@"score"];
    [object setObject:@"easy"
               forKey:@"mode"];
    [object setObject:[NSNumber numberWithBool:NO]
               forKey:@"premiumUser"];
    
    // 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 code above creates a KiiObject in the specified bucket, MyBucket in the user scope in this sample, on Kii Cloud.

In the code above, the setObject(_:forKey:) method is called to set values in three fields before the save(_:) method. For procedures for setting values, see Setting a Key-value Pair.

Creating a KiiObject with an ID

Kii Cloud automatically assigns an ID to a newly created KiiObject. You can also choose to have your mobile app to assign an ID to a KiiObject.

The following code creates a KiiObject with the same parameters as those in the previous example except that the ID is explicitly specified.

Swift:

  • let objectID = "score_userX"
    let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
    
    // Create a KiiObject with the specific ID.
    let object = bucket.createObject(withID: objectID)
    
    // Set key-value pairs.
    object.setObject(NSNumber(value: 987 as Int32), forKey: "score")
    object.setObject("easy", forKey: "mode")
    object.setObject(NSNumber(value: false as Bool), forKey: "premiumUser")
    
    do{
      // Save the KiiObject.
      try object.saveAllFieldsSynchronous(true)
    } catch let error as NSError {
      // Handle the error.
      return
    }
  • let objectID = "score_userX"
    let bucket = KiiUser.currentUser()!.bucketWithName("MyBucket")
    
    // Create a KiiObject with the specific ID.
    let object = bucket.createObject(withID: objectID)
    
    // Set key-value pairs.
    object.setObject(NSNumber(value: 987 as Int32), forKey: "score")
    object.setObject("easy", forKey: "mode")
    object.setObject(NSNumber(value: false as Bool), forKey: "premiumUser")
    
    // Save the KiiObject.
    object.saveAllFields(true, with: { (object : KiiObject?, error : Error?) -> Void in
      if (error != nil) {
        // Handle the error.
        return
      }
    })

Objective-C:

  • NSError *error = nil;
    KiiObject *object = nil;
    NSString *objectID = @"score_userX";
    KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
    
    @try {
      // Create a KiiObject with the specific ID.
      object = [bucket createObjectWithID:objectID];
    }
    @catch (NSException *exp) {
      // The KiiObject ID is invalid.
    }
    
    // Set key-value pairs.
    [object setObject:[NSNumber numberWithInt:987]
               forKey:@"score"];
    [object setObject:@"easy"
               forKey:@"mode"];
    [object setObject:[NSNumber numberWithBool:NO]
               forKey:@"premiumUser"];
    
    // Save the KiiObject.
    [object saveAllFieldsSynchronous:YES withError:&error];
    if (error != nil) {
      // Handle the error.
      return;
    }
  • KiiObject *object = nil;
    NSString *objectID = @"score_userX";
    KiiBucket *bucket = [[KiiUser currentUser] bucketWithName:@"MyBucket"];
    
    @try {
      // Create a KiiObject with the specific ID.
      object = [bucket createObjectWithID:objectID];
    }
    @catch (NSException *exp) {
      // The KiiObject ID is invalid.
    }
    
    // Set key-value pairs.
    [object setObject:[NSNumber numberWithInt:987]
               forKey:@"score"];
    [object setObject:@"easy"
               forKey:@"mode"];
    [object setObject:[NSNumber numberWithBool:NO]
               forKey:@"premiumUser"];
    
    // Save the KiiObject.
    [object saveAllFields:YES withBlock:^(KiiObject *object, NSError *error) {
      if (error != nil) {
        // Handle the error.
        return;
      }
    }];

You specify an ID when executing the createObject(WithID:) method. If you specify an invalid ID, an exception will be thrown (For the valid ID pattern, see the appledoc).

Call the saveAllFields(_:with:_:) method to create a new KiiObject with the specified ID on Kii Cloud. You cannot use the save(_:) method when you create a KiiObject with a specific ID.

If the KiiObject with the ID "score_userX" already exists on the server, the above sample code will overwrite the existing KiiObject. You can prevent this overwriting by setting the forced argument of the saveAllFields(_:with:_:) method to FALSE. See the appledoc for more details.

Tips for accessing KiiObjects

  • Cannot write in a bucket in the application scope

    All users, including anonymous users who have not logged in yet, can read the application scope. Writing in the application scope, however, requires the users to log in. If you want to avoid forcing your application users to log in, we recommend you to leverage the "pseudo user" feature (and not to change the ACL of the application scope). See Pseudo Users for more discussion.

    You need to be careful about the security when you are using the application scope. See Security for more details.

  • Cannot read a KiiObject that has been written in a bucket

    Double check if the scope of the bucket is correct.

    Remember that buckets in different scopes are separate even if they have the same name. The same applies when you use the data browser in the developer portal.

    For example, KiiObjects created in the application scope with Kii.bucket(withName:"myBucket") are not readable with Kii.currentUser().bucket(withName:"myBucket") because this method looks for the bucket in the user scope.