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