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.Hive(hiveName).KeyValueStore(keyName).set(value, options):Promise<boolean>

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.
{  
  expireAt: number,   // optional (in seconds)  
  ttl: number,         // optional (in seconds)  
  condition: 'IfExists' | 'IfNotExists' | 'Always'; // optional parameter, if not set, defaults to '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.
condition Optional parameter. This parameter sets a condition for when the key-value is created or modified. Supported values are:
'IfNotExists' -  a new key-value pair is created only if the specified key does not exist. If the key exists, the value is not updated.
'IfExists' -  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 'Always' 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 'Always', 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.

await Backendless.Hive('countries').KeyValueStore('Japan').set('The land of the rising sun', {
  ttl: 100,
  condition: 'Always'
})

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