sort.3valkey - Man Page

Sometimes you want to sort elements using external keys as weights to compare instead of comparing the actual elements in the list, set or sorted set. Let’s say the list mylist contains the elements 1, 2 and 3 representing unique IDs of objects stored in object_1, object_2 and object_3. When these objects have associated weights stored in weight_1, weight_2 and weight_3, SORT can be instructed to use these weights to sort mylist with the following statement:

SORT mylist BY weight_*

The BY option takes a pattern (equal to weight_* in this example) that is used to generate the keys that are used for sorting. These key names are obtained substituting the first occurrence of * with the actual value of the element in the list (1, 2 and 3 in this example).

The BY option can also take a non-existent key, which causes SORT to skip the sorting operation. This is useful if you want to retrieve external keys (see the GET option below) without the overhead of sorting.

SORT mylist BY nosort

Our previous example returns just the sorted IDs. In some cases, it is more useful to get the actual objects instead of their IDs (object_1, object_2 and object_3). Retrieving external keys based on the elements in a list, set or sorted set can be done with the following command:

SORT mylist BY weight_* GET object_*

The GET option can be used multiple times in order to get more keys for every element of the original list, set or sorted set.

It is also possible to GET the element itself using the special pattern #:

SORT mylist BY weight_* GET object_* GET #

Before 8.0, when enabling Valkey cluster-mode there is no way to guarantee the existence of the external keys on the node which the command is processed on. In this case, any use of GET or BY which reference external key pattern will cause the command to fail with an error.

Starting from 8.0, pattern with hash tag can be mapped to a slot, and so in Valkey cluster-mode, the use of BY or GET is allowed when pattern contains hash tag and implies a specific slot which the key is also in, which means any key matching this pattern must be in the same slot as the key, and therefore in the same node. For example, in cluster mode, {mylist}weight_* is acceptable as a pattern when sorting mylist, while pattern {abc}weight_* will be denied, causing the command to fail with an error.

To use pattern with hash tag, see valkey-cluster-spec(7) Hash tags for more information.

Any use of GET or BY which reference external key pattern will only be allowed in case the current user running the command has full key read permissions. Full key read permissions can be set for the user by, for example, specifying '%R~*' or '~* with the relevant command access rules. You can check the ACL SETUSER command manual for more information on setting ACL access rules. If full key read permissions aren’t set, the command will fail with an error.

By default, SORT returns the sorted elements to the client. With the STORE option, the result will be stored as a list at the specified key instead of being returned to the client.

SORT mylist BY weight_* STORE resultkey

An interesting pattern using SORT ... STORE consists in associating an EXPIRE timeout to the resulting key so that in applications where the result of a SORT operation can be cached for some time. Other clients will use the cached list instead of calling SORT for every request. When the key will timeout, an updated version of the cache can be created by calling SORT ... STORE again.

Note that for correctly implementing this pattern it is important to avoid multiple clients rebuilding the cache at the same time. Some kind of locking is needed here (for instance using SETNX).

It is possible to use BY and GET options against hash fields with the following syntax:

SORT mylist BY weight_*->fieldname GET object_*->fieldname

The string -> is used to separate the key name from the hash field name. The key is substituted as documented above, and the hash stored at the resulting key is accessed to retrieve the specified hash field.