Get Random Values¶

Description¶

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

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-random?count=[howMany]&withScores=[scores]

where:

Argument	Description
`[hive-name]`	Name of a hive where the operation is performed.
`[key]`	Key name identifying a sorted set.
`[howMany]`	Optional argument. If not present, defaults to 1. Specifies the number of items to return. The value can be positive or negative, in both cases the operation expresses different behavior, see the Response Body section below for more information.
`[scores]`	Optional parameter. When set to `true`, then the scores are returned along with the values. Otherwise, the scores are not returned. When the parameter is not present, it defaults to `false`.

Request Headers¶

None.

Request Body¶

None.

Response Body¶

Response is always a JSON array. When the scores are not included in the response (i.e. the [scores] 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 [howMany] parameter is a positive integer value, this operation has the following response behavior:

Identical elements are not returned when [howMany] is greater than 1.
If the [howMany] 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 [howMany] 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 [howMany] 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 [howMany] 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:

curl --location --request GET "https://xxxx.backendless.app/api/hive/players/sorted set/activePlayers/get-random?count=3&withScores=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
¶

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