Get Values By Score Range¶

Description¶

This operation returns values for a range of scores.

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-score?  
   minScore=[minScore]&  
   minBound=[minBound]&  
   maxScore=[maxScore]&  
   maxBound=[maxBound]&  
   offset=[offset]&  
   pageSize=[pageSize]&  
   withScores=[withScores]&  
   reverse=[reverse]

where:

Argument	Description
`[hive-name]`	Name of a hive where the operation is performed.
`[key]`	Key name identifying a sorted set.
`[minScore]/[maxScore]`	Minimum and maximum value of the scores to fetch the values of.To control whether the specified values are included or excluded from the range, use the `minBound`/`maxBound` parameters.
`[minBound]/[maxBound]`	Optional parameters. Available options are: `Include` - Includes value specified in the corresponding `minScore`/`maxScore` parameter into the range. `Exclude` - Excludes value specified in the corresponding `minScore`/`maxScore` parameter from the range. `Infinity` - Ignores the corresponding `minScore`/`maxScore` parameter and includes all consecutive score values that come before/after the defined score range. For example, if `minBound` is set to Infinity and `maxScore` is set to 5, the query will include all values with scores less than 5.
`[offset]`	Optional parameter. Sets the index/position from which to retrieve the items. For example, if the resulting set contains 10 items, then by setting the `offset` parameter to 2, the first 2 values in the range will be skipped, while the remaining 8 returned in the response.
`[pageSize]`	Optional parameter. If not set, defaults to 20. Sets the number of items to include in the response. Maximum supported value is 10000.
`[withScores]`	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`.
`[reverse]`	Optional parameter. When the parameter is not present, it 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 [withScores] 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. When the [withScores] parameter is set to false, the return value is a JSON array of values.

Example¶

The example returns all values in the range of scores between 0 and 3.

curl --location --request GET "http://xxxxx.backendless.app/api/hive/banking/sorted set/leaderboard/get-range-by-score?minScore=0&maxScore=3&withScores=true"

Response Body

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

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

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

Codeless Reference
¶

where:

Argument	Description
`hive name`	Name of a hive where the operation is performed.
`key name`	Key name identifying a sorted set.
`min/max score`	Score values between which the items are requested. To control whether the specified values are included or excluded from the range, use the `min`/`max bound` parameters.
`min/max bound`	Parameters that control the presence of the first and last values in the range. Each of these parameters has three options: `Include` - Includes value specified in the corresponding `min score`/`max score` parameter into the range. `Exclude` - Excludes value specified in the corresponding `min score`/`max score` parameter from the range. `Infinity` - Ignores the corresponding `min score`/`max score` parameter and includes all consecutive score values that come before/after the defined score range. For example, if `min bound` is set to Infinity and `max score` is set to 5, the query will include all values with scores less than 5. These parameters default to `Include`.
`offset`	Sets a zero-based index/position from which to retrieve the items. For example, if the resulting set contains 10 items, then by setting the `offset` parameter to 2, the first 2 values in the range will be skipped, while the remaining 8 returned in the response.
`page size`	If not set, defaults to 20. Sets the number of items to include in the response. Maximum supported value is 10000.
`with score`	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`.
`reverse`	When set to `true`, items are sorted in ascending order. If set to `false`, items are sorted in descending order.

When the with score 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 returns values in the range of scores between 0 (inclusively) and to 5 (inclusively).

Since the with score parameter is set to true, the keys are returned alongside with the corresponding scores.
Since the reverse parameter is set to true, the items are sorted by rank in descending order.
The page size parameter is set to 3, indicating that the service should return 3 items in the response.
The offset parameter is set to 1, the returned items are included from the first (zero-based) position.

sorted_set_api_example_get_values_by_score_range

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