Skip to content

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

Backendless.Hive( hiveName ).SortedSetStore( keyName ).getRangeByRank(   
   startRank,   
   stopRank,   
   {   
      withScores: boolean,   
      reverse: boolean   
   }): Promise;


where:

Argument                Description
hiveName Name of a hive where the operation is performed. Must be a string.
keyName Key name identifying a sorted set. Must be a string.
startRank/stopRank 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 stopRank 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.
withScores Optional parameter, defaults to false.When this parameter is set to true, then the item score is returned.
reverse Optional parameter, defaults to false. When set to false, items in the requested sorted set are sorted in ascending order of their scores.  When set to true, items are sorted in   descending order of their scores.

Return Value

When the withScores parameter is set to true, the return value is an array of score-value pairs. Each pair is also an array of two elements - the score and the value. When the withScores parameter is set to false, the return value is an array of values.

Example

The example below retrieves sorted set values with ranks between 1 and 3 inclusively. Since withScores parameter is set to true, the scores are included into the response. Notice the reverse parameter is set to true, as a result, items in the sorted set are sorted in descending order of their scores.

await Backendless.Hive('demoName').SortedSetStore('leaderboard').getRangeByRank(1, 3, { withScores: true, reverse: true })

Response

[  
    [  
        3.0,  
        "player_30"  
    ],  
    [  
        2.0,  
        "player_20"  
    ],  
    [  
        1.0,  
        "player_10"  
    ]  
]

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

[  
    "player_30",  
    "player_20",  
    "player_10"  
]

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