Get Values By Rank Range¶

Description¶

This operation returns values for a range of rank numbers. A rank in a sorted set determines the position of an element. For more information about the rank, refer to the Hive Overview section of this guide.

Method¶

GET

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]/get-range-by-rank?  
   startRank=[startRank]&  
   stopRank=[stopRank]&  
   withScores=[scores]&  
   reverse=[orderControl]

where:

Argument	Description
`[hive-name]`	Name of a hive where the operation is performed.
`[key]`	Key name identifying a sorted set.
`[startRank/stopRank]`	These parameters establish a range of ranks. Operation returns the values in the specified range. In case you do not know the rank of the last element in the sorted set, you can assign to `[stopRank]` a negative rank of `-1` that represents the highest available rank. Negative numbers other than `-1` assigned to `[stopRank]` designate an item located in the specified position from the end. For instance `[stopRank]` of `-2` identified the penultimate item.
`[scores]`	Optional parameter. When set to `true`, then the scores are returned along with the values. Otherwise, when set to `false`, the scores are not returned. When the parameter is not present, it defaults to `false`.
`[orderControl]`	Optional parameter, defaults to `false`. When set to `false`, items in the specified sorted set are sorted in ascending order of their scores. When set to `true`, items are sorted in descending order of their scores.

Request Headers¶

None.

Request Body¶

None.

Response Body¶

When the [scores] parameter is set to true, the return value is a JSON array of score-value pairs. Each pair is also an array of two elements - the score and the value.

Example¶

The example below returns an array of score-value pairs where the values are within a range identified by the startRank and the stopRank parameters. Since the [scores] parameter is set to true, the response includes both values and the corresponding scores.

curl --location --request GET "https://xxxx.backendless.app/api/hive/leaderboard/sorted-set/players/get-range-by-rank?startRank=1&stopRank=4&withScores=true"

where:

Argument	Description
`leaderboard`	Name of a hive in the system.
`players`	Name of a sorted set where the operation takes place.

Response

[  
    [  
        1.0,  
        "Player B"  
    ],  
    [  
        2.0,  
        "Player A"  
    ],  
    [  
        3.0,  
        "Player F"  
    ]  
]

If the withScores parameter is set to false or is not present, the response does not include the scores:

[  
   "Player B",  
   "Player A",  
   "Player F"  
]

Codeless Reference¶

sorted_set_api_get_values_by_rank_range

where:

Argument	Description
`hive name`	Name of a hive where the operation is performed.
`key name`	Key name identifying a sorted set.
`from/to`	The inclusive range of ranks (positions) of elements, between which the items are requested (the maximum for returning elements is the difference between these two parameters which cannot be bigger than 10000); The `to` parameter can also be a negative number indicating offset from the end of the sorted set, with -1 being the last element of the sorted set, -2 the penultimate element, and so on.
`with score`	Set this parameter to `true` if you want to return values with their scores.
`reverse`	When set to `true`, items are sorted in ascending order. If set to `false`, items are ordered in descending order.

This operation returns values for a range of rank numbers. A rank in a sorted set determines the position of an element. For more information about the rank, refer to the Hive Overview section of this guide.

When the with scores parameter is set to true, the return value is a list of score-value pairs. Each pair is also a list of two elements - the score and the value. When the with scores parameter is set to false, the return value is a list of values.

Consider the following Sorted Set storage:
sorted_set_api_example_all_blocks

The example below retrieves values in the rank range starting from 0 to 2 from the "players" sorted set.
sorted_set_api_example_get_values_by_rank_range

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