Skip to content

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

[[[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:

@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:

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.

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

keyvalue_api_set_key_value

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:

sample-key-value

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

keyvalue_api_example_set_key_value


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