Add Items¶

Description¶

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

Method¶

PUT

Endpoint URL¶

Important

Make sure to replace xxxx in the domain name in the request specification below to the one assigned to your application.

https://xxxx.backendless.app/api/hive/[hive-name]/sorted set/[key]/add

where:

Argument	Description
`[hive-name]`	Name of a hive where the operation is performed.
`[key]`	Key name identifying a sorted set store.

Request Headers¶

Content-Type:application/json

where:

Argument	Description
`Content-Type`	Must be set to `application/json`. This header is mandatory.

Request Body¶

The request body must be a JSON object with the structure shown below:

      {  
        "items":             [ [score,value], [score,value], ... ],  
        "duplicateBehavior": "OnlyUpdate" | "AlwaysAdd",  // optional  
        "scoreUpdateMode":   "Greater" | "Less",          // optional  
        "resultType":        "NewAdded" | "TotalChanged"  // optional  
      }

where:

Argument	Description
`"items"`	A JSON array of values and their scores. Each score and value must be placed into a separate (child) array of 2 elements (a score followed by value). The data type of score must be double, the data type of value is any valid JSON.
`"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 are 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"`.

Response Body¶

The number of added or updated items 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".

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 since"duplicateBehaviour" parameter is set to the "OnlyUpdate" option.

curl --location --request PUT "https://xxxx.backendless.app/api/hive/leaderboard/sorted set/players/add" \  
        --header 'Content-Type: application/json' \  
        --data-raw '[  
                "items":[ [25, "John"]],  
                "duplicateBehavior": "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: