Skip to content

Get Random Values

Description

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

Method.

Get one random value

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

Get multiple random values:

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

where:

Argument                Description
hiveName Name of a hive in the system where the operation is performed. Must be a string.
keyName  Key name of a sorted set where to get random values from.
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 {withScore:boolean} parameter is set to false or is not present), the response array elements are the random values. 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 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 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 behavior:

  • Repeated (same) elements can be returned in the response.
  • 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 is truly random.


Example

The example below will return an array containing 3 random score-value pairs from the 'leaderboard' sorted set.

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

where:

Argument                Description
'hiveName' Name of a hive where the operation is performed.
'leaderboard' The name of a sorted set to get random score-value pairs.

Response

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

If the withScore parameter is set to false or is not present, the response does not include 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