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 in the system where the operation is performed. Must be a string.
keyName	Key name of a sorted set to add new items. Must be a string value.
items	An array of items to add to the sorted set. Each element of the array, must be an array consisting of two elements: score as a number and the assigned value of any JavaScript 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 is based on the "resultType" parameter 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".

Examples

With The options Parameter

The example below updates two score-value pairs in the 'players' sorted set. The scoreUpdateMode parameter uses the 'Greater' option, which means that scores will be updated only if the new score of an item is greater than the existing score in the sorted set. The resultType parameter uses the 'TotalChanged' option, which instructs the operation to return the number of modified items.

await Backendless.Hive('leaderboard').SortedSetStore('leaderboard').add(  
  [[51, 'Bob'], [122, 'Mike']], {  
    duplicateBehaviour: 'OnlyUpdate',  
    scoreUpdateMode   : 'Greater',  
    resultType        : 'TotalChanged'  
  }  
)

where:

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

Without The options Parameter

The example below adds the new item [1.25, 'John'] to the 'players' sorted set. If an item with the same value already exists in the sorted set, then the item's score is updated.

await Backendless.Hive('leaderboard').SortedSetStore('players').add([[1.25, 'John']])

where:

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

Codeless Reference

where:

Argument	Description
hive name	Name of a hive where the operation is performed.
key name	Key name identifying a sorted set.
items	Nested list containing scores and values to add to the sorted set.
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:


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


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