Set Key-Value

Description

This operation modifies a value associated with the specified key. In case the specified key does not exists, a new key-value pair is created.

Method

Objective-CSwift

[[[Backendless.shared hive:(NSString *)hiveName] keyValueStore:(NSString *)keyName] setWithValue:(id)value options:(KeyValueSetKeyOptions *)options responseHandler:^(BOOL)responseHandler errorHandler:^(Fault *)errorHandler];

Backendless.shared.hive(hiveName: String).keyValueStore(keyName: String).set(value: Any, options: KeyValueSetKeyOptions, responseHandler: ((Bool) -> Void)!, errorHandler: ((Fault) -> Void)!)

where:

Argument	Description
hiveName	Name of a hive where the operation is performed. String value.
keyName	Key name identifying a key-value pair. String value.
value	A new value to assign to the key. Can be of any data type.
options	Optional parameter. Defines the behavior of this operation. Must be an object with the structure provided below.

KeyValueSetKeyOptions object structure:

Objective-CSwift

@interface KeyValueSetKeyOptions : NSObject

@property (nonatomic) NSInteger ttl;
@property (nonatomic) NSInteger expireAt;
@property (nonatomic) enum KeyValueSetCondition condition;

@end

@objcMembers public class KeyValueSetKeyOptions: NSObject {
    public var ttl: Int = 0
    public var expireAt: Int = 0
    public var condition: KeyValueSetCondition = .always
}

where:

Argument	Description
expireAt	Optional parameter. A Unix timestamp identifying a moment in time when the key-value pair must expire and be subsequently removed from the store. The Unix time is the number of seconds elapsed since 1970-01-01 00:00:00 UTC.
ttl	Optional parameter. This parameter is interpreted as a number of seconds after the value is created or updated when the key-value pair expires and is subsequently removed from the store. If the request contains values for both ttl and expireAt , the ttl parameter is ignored.
KeyValueSetCondition	Optional parameter. This parameter sets a condition for when the key-value is created or modified. The structure  is shown further.

KeyValueSetCondition  structure:

Objective-CSwift

typedef SWIFT_ENUM(NSInteger, KeyValueSetCondition, closed) {
  KeyValueSetConditionIfExists = 0,
  KeyValueSetConditionIfNotExists = 1,
  KeyValueSetConditionAlways = 2,
};

@objc public enum KeyValueSetCondition: Int{
    case ifExists
    case ifNotExists
    case always
}

where:

Argument	Description
ifExists	a new key-value pair is created only if the specified key does not exist. If the key exists, the value is not updated.
ifNotExists	the value is updated only if the specified the key exists. If the key does not exist, a new key-value pair is not created.
always	works both ways and creates a new value if it does not exist or modifies an existing value if the key exists.

Return Value

The operation returns true when:

• The condition parameter is set to KeyValueSetConditionAlways or;
• The condition is met for the ifExists or the ifNotExists options

In all other cases, the return value is false.

Example

The example below modifies the value associated with the key "Japan" to "The land of the rising sun". The condition parameter is set to KeyValueSetConditionAlways, as a result, if the specified key does not exist, a new key-value pair is created.

The ttl parameter is set to 100 seconds, as a result, the newly created/modified key is deleted by the system 100 seconds after the call.

Objective-CSwift

KeyValueSetKeyOptions *options = [KeyValueSetKeyOptions new];
options.ttl = 100;
options.condition = KeyValueSetConditionAlways;

[[[Backendless.shared hive:@"countries"]keyValueStore:@"Japan"] setWithValue:@"The land of the rising sun" options:options  responseHandler:^(BOOL response) {
    // handle response
} errorHandler:^(Fault *fault) {
    // handle error
}];

let options = KeyValueSetKeyOptions()
options.ttl = 100
options.condition = .always

Backendless.shared.hive("countries").keyValueStore("Japan").set(value: "The land of the rising sun", options: options, responseHandler: { response in
    // handle response
}, errorHandler: { fault in
    // handle error
})

where:

Argument	Description
"country"	Name of a hive where the operation is performed.
"Japan"	A key to modify the value for.
"The land of the rising sun"	The new value to assign to the key.

Codeless Reference

where:

Argument	Description
hive name	Name of a hive where the operation is performed.
key name	Key name identifying a key-value pair.
value	A new value for a key.
expire	Expiration timeout type. Can be set to seconds after or on timestamp/date. The seconds after identifies the number of seconds until the key expires. The on timestamp/date identifies a Unix timestamp/date when the key must expire. This option expects the number of seconds in the Unix format.
expire condition	Sets a condition for when the key-value is created or modified. There are three supported conditions: If Exists - a new key-value pair is created only if the specified key does not exist. If the key exists, the value is not updated. If Doesn't Exist - the value is updated only if the specified the key exists. If the key does not exist, a new key-value pair is not created. Always - works both ways and creates a new value if it does not exist or modifies an existing value if the key exists.

Returns a boolean value depending on the selected parameters.

Consider the following Key Value storage:

The example below a value for the "Japan" key:

The key-value storage will look as shown below after the Codeless logic runs: