Skip to content

Get Random Values

Description

This operation returns the specified number of random values from a sorted set.

Method

Backendless.Hive( hiveName ).SortedSetStore( keyName ).getRandom( {withScore: boolean, count:number} ): Promise<items>;

where:

Argument                Description
hiveName Name of a hive where the operation is performed. String value.
keyName Key name identifying a sorted-set. String value.
withScore Optional parameter (the entire object argument can be skipped). 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.
count Optional argument. If not present, defaults to 1. Sets the number of items to return. The value can be positive or negative, in both cases the operation expresses different behavior, see the Return Value section below for more information.

Return Value

Response is always an array. When the scores are not included in the response (i.e. the withScores parameter is set to false or is not present), the response array elements are random values from the sorted-set. When the scores are included, the response array elements are arrays consisting of two items - score and the corresponding value.

When the count parameter is a positive integer value, this operation has the following response behavior:

  • Identical elements are not returned when count is greater than 1.
  • If the count parameter is greater than the total number of items in the sorted set, the API will return the entire sorted set.
  • An empty array is returned if the key is empty or does not exist.
  • When count is greater than 1, the order of elements in the response is not truly random - they are sequenced according to the score values.

When the count parameter is a negative integer value then this operation has the following response behavior:

  • Repeated (same) elements can be returned in the response body.
  • An empty array is returned if the key is empty or does not exist.
  • When count is less than -1, the order of elements in the response body is truly random.

Example

The example below returns three random items from the 'activePlayers' sorted set: 

await Backendless.Hive('hiveName').SortedSetStore('leaderboard').getRandom(3, true)

where:

Argument                Description
'players' Name of a hive where the operation is performed.
'activePlayers' The name of a sorted set to get random key-value pairs.

Response

[  
    [  
        22.0,  
        "Joe"  
    ],  
    [  
        100.0,  
        "Bob"  
    ],  
    [  
        155.0,  
        "Becky"  
    ]  
]

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

[  
  "Joe",  
  "Bob"  
  "Becky"  
]

Codeless Reference
sorted_set_api_get_random_values

where:

Argument                Description
hive name Name of a hive where the operation is performed.
key name Key name identifying a sorted set.
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.
count Sets the number of items to return. The value can be positive or negative, in both cases the operation expresses different behavior, see the information below.

Response is always a list. When the scores are not included in the response (i.e. the with score parameter is set to false or is not present), the response list elements are the random values. When the scores are included, the response list elements are lists consisting of two items - score and the corresponding value.

When the count parameter is a positive integer value then this operation has the following behavior:

  • Identical elements are not returned when count is greater than 1.
  • If the count parameter is greater than the total number of items in the sorted set, the API will return the entire sorted set.
  • An empty list is returned if the key is empty or does not exist.
  • When count is greater than 1, the order of elements in the response is not truly random - they are sequenced according to the score values.

When the count parameter is a negative integer value then this operation has the following behavior:

  • Repeated (same) elements can be returned in the response.
  • An empty list is returned if the key is empty or does not exist.
  • When count is less than -1, the order of elements in the response is truly random.

Consider the following Sorted Set storage:
sorted_set_api_example_all_blocks

The example below retrieves 1 random score-value pair from the "players" sorted set:
sorted_set_api_example_get_random_values

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