Add Items¶

Description¶

This operation adds or updates values and scores in a sorted set.

Method¶

Backendless.Hive( hiveName ).SortedSetStore( keyName ).add( items, options ): Promise<number>;

where:

Argument	Description
`hiveName`	Name of a hive where the operation is performed. String value.
`keyName`	Key name identifying a sorted-set. String value.
`items`	An array of items to add to the sorted set. Each element of the main array, must be a secondary/child array consisting of two parts: score as a number and the assigned value of any type.
`options`	An object with the structure shown below:

{  
    duplicateBehaviour: 'OnlyUpdate' | 'AlwaysAdd',  
    scoreUpdateMode:    'Greater' | 'Less',  
    resultType:         'NewAdded' | 'TotalChanged'  
}

where:

Argument	Description
`duplicateBehavior`	Optional parameter. Controls how the duplicate values in the sorted set are handled. The parameter can be set to either `'OnlyUpdate'` or `'AlwaysAdd'`. With the `'OnlyUpdate'` option, only values included in the request that already exist in the sorted set will be updated. New items won't be added. With the `'AlwaysAdd'` option, existing items will not modified and new ones from the request are added.
`scoreUpdateMode`	Optional parameter. Enables conditional update based on the score of an item. The parameter can be set to either `'Greater'` or `'Less'` options. With the `"Greater"` option existing items in the sorted set are updated if the new score is greater than the current score. With the `'Less'` option, existing items in the sorted set are updated if the new score is less than the current score.
`resultType`	Optional parameter. Controls how the number of items added or updated is calculated for the return value. The parameter can be set to the `'NewAdded'` or `'TotalChanged'` options. With the `'NewAdded'` option, the operation returns the number of newly added items to the sorted set. With the `'TotalChanged'` option, the operation returns the number of the modified items. If the parameter is not present in the request, the operation defaults to `'NewAdded'`.

Return Value¶

The number of added or updated items based on the resultTypeparameter in the request. When resultType is set to the 'NewAdded' option, the operation returns the number of newly added items to the sorted set. When resultType is set to the 'TotalChanged' option, the operation returns the number of the modified items. If the parameter is not present in the request, the operation defaults to 'NewAdded'.

Example¶

The example below adds the new item [25, "John"] to the 'players' sorted set. If the item already exists in the sorted set, it is updated sinceduplicateBehaviour parameter is set to the 'OnlyUpdate' option.

await Backendless.Hive('leaderboard').SortedSetStore('leaderboard').add(
  [[25, 'John']], {
    duplicateBehaviour: 'OnlyUpdate',
    scoreUpdateMode   : 'Greater',
    resultType        : 'TotalChanged'
  }
)

where:

Argument	Description
`'leaderboard'`	Name of a hive in the system.
`'players'`	Name of the sorted set to perform the operation in.

Codeless Reference¶

sorted_set_api_add_key_items

where:

Argument	Description
`hive name`	Name of a hive where the operation is performed.
`key name`	Key name identifying a sorted set.
`items`	A list of containing scores and values to add to the sorted set. Every item in the main list is also a list consisting of two elements - a score and a value.
`duplicate behavior`	Controls how the duplicate values in the sorted set are handled. This parameter has two conditions: `Only Update` - Values included in the request that already exist in the sorted set will be updated. New items won't be added. `Always Add` - Existing items in the sorted set remain unmodified, while the new ones are added.
`score update mode`	Enables conditional update based on the score of an item. This parameter has two conditions: `Greater` - Existing items in the sorted set are updated if the new score is greater than the current score `Less` - Existing items in the sorted set are updated if the new score is less than the current score
`result type`	Controls how the number of items added or updated is calculated for the return value. This parameter has two conditions: `New Added` - When set to this option, the operation returns the number of newly added items to the sorted set. `Total Changed` - When set to this option, the operation returns the number of the modified items.

The operation returns the number of added or updated items based on the result type parameter in the request. When result type is set to the New Added option, the operation returns the number of newly added items to the sorted set. When result type is set to the Total Changed option, the operation returns the number of the modified items. If the parameter is not present in the request, the operation defaults to New Added.

Consider the following Sorted Set storage:
sorted_set_api_example_all_blocks

The example below adds two new score-value pairs [23,"Mike"] and [33,"Peter"] to the "players" sorted set.
sorted_set_api_example_add_key_items

The output will look as shown below after the Codeless logic runs: