The TairZset data structure allows you to sort data of the DOUBLE type based on multiple dimensions. It is ideal for implementing leaderboards for use in industries such as gaming, live streaming, music, and e-commerce. TairZset improves data processing efficiency and is also easy to implement on the client side because you do not need to encode, decode, or encapsulate the data.
Overview
The Sorted Set data structure of open source Redis, which is also known as ZSET, allows you to sort DOUBLE-typed scores only by one dimension. It is difficult to use ZSET to sort data from multiple dimensions. For example, you can use the IEEE Standard for Floating-Point Arithmetic (IEEE 754) standard to implement multidimensional sorting by concatenating score data. However, this method has drawbacks, such as complex logic, reduced precision, and unavailability of the EXZINCRBY command.
- Allows DOUBLE-typed scores to be sorted from a maximum of 256 dimensions. The scores
are displayed from left to right based on their priorities.
In a multidimensional sorting, a left score has higher priority than a right score. Take the comparison of three-dimensional scores in the score1#score2#score3 format as an example. TairZset compares the score1s of multiple three-dimensional scores and moves on to score2s only when score1s are equal. If score1s are not equal, the ranking of score1s represents the ranking of the three-dimensional scores involved. By the same logic, score3s are compared only if score2s are equal. If all score1s are equal and the same holds true for score2s and score3s, the involved multidimensional scores are ranked in ASCII sort order.
For easier understanding, you can imagine number signs (#) as decimal points (.). This way, 0#99 < 99#90 < 99#99 can be seen as 0.99 < 99.90 < 99.99.
- Supports the EXZINCRBY command. You no longer need to retrieve current data, apply the increments to the data, and then write the data to Redis databases.
- Supports APIs similar to those available for native Redis ZSET.
- Supports the open-sourced TairJedis client. For more information about the TairJedis client, see alibabacloud-tairjedis-sdk. You can use the TairJedis client without the need to encode, decode, or encapsulate data. You can also encapsulate clients for other programming languages by referring to open-sourced code.
- Leaderboards for the live streaming industry: In live matches, commentators are sorted by their current popularity value. If the popularity value is the same, they are sorted by the number of their likes. If the number of likes is also the same, they are sorted by the value of their gifts.
- Leaderboards for medals: Participants are sorted by the number of their gold, silver, and bronze medals. If the number of gold medals is the same, they are sorted by the number of silver medals. If the number of silver medals is also the same, they are sorted by the number of bronze medals.
- Leaderboards for the gaming industry: Players are sorted based on multiple factors, including their scores, task completion speeds, and achievement levels.
The module is open-sourced. For more information, see TairZset.
Best practices
Prerequisites
- The instance is a performance-enhanced instance of the ApsaraDB for Redis Enhanced Edition (Tair). For more information, see Performance-enhanced instances.
- The instance is updated to the latest minor version. For more information, see Update the minor version.
Note If your instance is a cluster instance or read/write splitting instance, the proxy nodes in your instance must also be of the latest minor version to ensure that all commands can be run as expected. For more information about cluster instances and read/write splitting instances, see Cluster master-replica instances and Read/write splitting instances.
Precautions
The TairZset data that you want to manage is stored on the performance-enhanced instance.
TairZset commands
Command | Syntax | Description |
---|---|---|
EXZADD | EXZADD key [NX|XX] [CH] [INCR] score member [score member ...] |
Stores the specified element and its score in a TairZset key. You can specify multiple
scores and elements.
Note To implement multidimensional sorting, you can separate the scores of each dimension
with number signs (#), such as
111#222#121 . All elements of a key must have the same score format.
|
EXZINCRBY | EXZINCRBY key increment member |
Increases the score of an element in a TairZset key. increment indicates the value that you want to add to the score. |
EXZSCORE | EXZSCORE key member |
Returns the score of an element in a TairZset key. If the key or the element does not exist, a value of nil is returned. |
EXZRANGE | EXZRANGE <key> <min> <max> [WITHSCORES] |
Returns the elements of a TairZset key within the specified score range. |
EXZREVRANGE | EXZREVRANGE <key> <min> <max> [WITHSCORES] |
Returns the elements of a TairZset key within the specified score range. Elements
are stored by score in descending order, and elements with the same score are sorted
in reverse lexicographical order.
Note This command is similar to EXZRANGE except that this command sorts the results in reverse.
|
EXZRANGEBYSCORE | EXZRANGEBYSCORE <key> <min> <max> [WITHSCORES] [LIMIT offset count] |
Returns the elements of a TairZset key whose scores are greater than or equal to the min value and are less than or equal to the max value. The returned elements are sorted by score in ascending order, and elements with the same score are returned in lexicographical order. |
EXZREVRANGEBYSCORE | EXZREVRANGEBYSCORE <key> <max> <min> [WITHSCORES] [LIMIT offset count] |
Returns the elements of a TairZset key whose scores are greater than or equal to the
min value and are less than or equal to the max value. Contrary to the default sorting of TairZset elements, the elements returned
by this command are sorted by score in descending order, and elements with the same
score are sorted in reverse lexicographical order.
Note This command is similar to EXZRANGEBYSCORE except that this command sorts the results in reverse and places max in front of min.
|
EXZRANGEBYLEX | EXZRANGEBYLEX <key> <min> <max> [LIMIT offset count] |
Returns the elements whose scores are between the min value and the max value when all elements of a key have the same score to ensure that elements are sorted in lexicographical order. |
EXZREVRANGEBYLEX | EXZREVRANGEBYLEX <key> <max> <min> [LIMIT offset count] |
Returns the elements whose scores are between the min value and the max value when
all elements of a key have the same score to ensure that elements are sorted in lexicographical
order.
Note This command is similar to EXZRANGEBYLEX except that this command sorts the results in reverse and places max in front of min.
|
EXZREM | EXZREM key member [member ...] |
Removes specified elements from a TairZset key. If the specified element does not exist, the element is ignored. |
EXZREMRANGEBYSCORE | EXZREMRANGEBYSCORE key min max |
Removes the elements from a TairZset key whose scores are greater than or equal to the min value and are less than or equal to the max value. |
EXZREMRANGEBYRANK | EXZREMRANGEBYRANK key start stop |
Removes the elements from a TairZset key whose ranks are within the range of the start value and the stop value. |
EXZREMRANGEBYLEX | EXZREMRANGEBYLEX key min max |
Removes the elements whose scores are between the min value and the max value when
all elements of a key have the same score to ensure that elements are sorted in lexicographical
order.
Note If you use the min and max parameters to specify the same range for the EXZREMRANGEBYLEX and EXZRANGEBYLEX commands, the elements removed by the EXZREMRANGEBYLEX command are the same as those
returned by the EXZRANGEBYLEX command.
|
EXZCARD | EXZCARD key |
Returns the cardinality of a TairZset key. Cardinality indicates the number of elements in a key. |
EXZRANK | EXZRANK key member |
Returns the rank of an element in a TairZset key. Ranks are sorted by score in ascending order. Ranks use a zero-based numbering scheme, and the rank of the element that has the lowest score is 0. Rank is also known as index. |
EXZREVRANK | EXZREVRANK key member |
Returns the rank of an element in a TairZset key. Ranks are sorted by score in descending
order. Ranks use a zero-based numbering scheme, and the rank of the element that has
the highest score is 0. Rank is also known as index.
Note This command is similar to EXZRANK except that this command sorts the results in reverse.
|
EXZCOUNT | EXZCOUNT key min max |
Returns the number of elements in a TairZset key whose scores are between the min value and the max value. |
EXZLEXCOUNT | EXZLEXCOUNT key min max |
Returns the elements whose scores are between the min value and the max value when all elements of a key have the same score to ensure that elements are sorted in lexicographical order. |
EXZRANKBYSCORE | EXZRANKBYSCORE key score |
Calculates the rank of the specified element score in a TairZset key. Ranks are sorted
by score in ascending order. Ranks use a zero-based numbering scheme, and the rank
of the element that has the lowest score is 0. Rank is also known as index.
Note If the score does not exist, the estimated rank of the score in the key is returned.
If the score already exists, Tair ranks the score in front of other existing scores
in the key by default.
|
EXZREVRANKBYSCORE | EXZREVRANKBYSCORE key score |
Calculates the rank of the specified score in a TairZset key. Ranks are sorted by
score in descending order. Ranks use a zero-based numbering scheme, and the rank of
the element that has the highest score is 0. Rank is also known as index.
Note If the score does not exist, the estimated rank of the score in the key is returned.
If the score already exists, Tair ranks the score behind other existing scores in
the key by default.
|
DEL | DEL key [key ...] |
Deletes one or more TairZset keys. |
EXZADD
Item | Description |
---|---|
Syntax | EXZADD key [NX|XX] [CH] [INCR] score member [score member ...] |
Time complexity | O(N) |
Command description | Adds the specified element with the specified score to a TairZset key. You can specify
multiple scores and elements. The system uses different strategies based on whether
the key and element exist:
Note To implement multidimensional sorting, you can separate the scores of each dimension
with number signs (#), such as
111#222#121 . All elements of a key must have the same score format.
|
Parameter |
|
Output | The output is an integer. The following rules describe the output:
|
Example |
Sample command:
Sample output:
|
EXZINCRBY
Item | Description |
---|---|
Syntax | EXZINCRBY key increment member |
Time complexity | O(log(N)) |
Command description | Increases the score of an element in a TairZset key. increment indicates the value that you want to add to the score. The system uses different
strategies based on whether the key and element exist:
Note
|
Parameter | N/A |
Output | The new score of an element as a string. If multidimensional scores are used, the
scores are returned in the "score1# score2# score3#..." format, such as 2#0#6 .
|
Example |
Sample command:
Sample output:
|
EXZSCORE
Item | Description |
---|---|
Syntax | EXZSCORE key member |
Time complexity | O(1) |
Command description | Returns the score of an element in a TairZset key. If the key or the element does not exist, a value of nil is returned. |
Parameter | N/A |
Output | The score of an element as a string. If multidimensional scores are used, the scores
are returned in the "score1# score2# score3#..." format, such as 2#0#6 .
|
Example |
Sample command:
Sample output:
|
EXZRANGE
Item | Description |
---|---|
Syntax | EXZRANGE <key> <min> <max> [WITHSCORES] |
Time complexity | O(log(N)+M), where N indicates the number of elements in the TairZset key and M indicates the number of elements returned. |
Command description | Returns the elements of a TairZset key within the specified score range. |
Parameter |
|
Output | A list of elements within the specified score range. If the WITHSCORES parameter is specified, the scores of elements are returned. |
Example |
Sample command:
Sample output:
|
EXZREVRANGE
Item | Description |
---|---|
Syntax | EXZREVRANGE <key> <min> <max> [WITHSCORES] |
Time complexity | O(log(N)+M), where N indicates the number of elements in the TairZset key and M indicates the number of elements returned. |
Command description | Returns the elements of a TairZset key within the specified score range. Elements
are stored by score in descending order, and elements with the same score are sorted
in reverse lexicographical order.
Note This command is similar to EXZRANGE except that this command sorts the results in reverse.
|
Parameter |
|
Output |
A list of elements within the specified score range. If the WITHSCORES parameter is specified, the scores of elements are returned. |
Example |
Sample command:
Sample output:
|
EXZRANGEBYSCORE
Item | Description |
---|---|
Syntax | EXZRANGEBYSCORE <key> <min> <max> [WITHSCORES] [LIMIT offset count] |
Time complexity | O(log(N)+M), where N indicates the number of elements in the TairZset key and M indicates
the number of elements returned.
Note When M is set to a constant, this expression can be regarded as O(log(N)). For example,
you can specify that the first 10 elements are always returned by using the LIMIT
offset count parameter.
|
Command description | Returns the elements of a TairZset key whose scores are greater than or equal to the min value and are less than or equal to the max value. The returned elements are sorted by score in ascending order, and elements with the same score are returned in lexicographical order. |
Parameter |
|
Output |
A list of elements within the specified score range. If the WITHSCORES parameter is specified, the scores of elements are returned. |
Example |
Sample command:
Sample output:
|
EXZREVRANGEBYSCORE
Item | Description |
---|---|
Syntax | EXZREVRANGEBYSCORE <key> <max> <min> [WITHSCORES] [LIMIT offset count] |
Time complexity | O(log(N)+M), where N indicates the number of elements in TairZset, and M indicates
the number of elements returned.
Note When M is set to a constant, this expression can be regarded as O(log(N)). For example,
you can specify that the first 10 elements are always returned by using the LIMIT
offset count parameter.
|
Command description | Returns the elements of a TairZset key whose scores are greater than or equal to the
min value and are less than or equal to the max value. Contrary to the default sorting of TairZset elements, the elements returned
by this command are sorted by score in descending order, and elements with the same
score are sorted in reverse lexicographical order.
Note This command is similar to EXZRANGEBYSCORE except that this command sorts the results in reverse and places max in front of min.
|
Parameter |
|
Output |
A list of elements within the specified score range. If the WITHSCORES parameter is specified, the scores of elements are returned. |
Example |
Sample command:
Sample output:
|
EXZRANGEBYLEX
Item | Description |
---|---|
Syntax | EXZRANGEBYLEX <key> <min> <max> [LIMIT offset count] |
Time complexity | O(log(N)+M), where N indicates the number of elements in the TairZset key and M indicates
the number of elements returned.
Note When M is set to a constant, this algorithm can be regarded as O(log(N)). For example,
you can specify that the first 10 elements are always returned by using the LIMIT offset count parameter.
|
Command description | Returns the elements whose scores are between the min value and the max value when all elements of a key have the same score to ensure that elements are
sorted in lexicographical order.
Note
|
Parameter |
|
Output | The elements whose values are within the specified range. |
Example |
Sample command:
Sample output:
|
EXZREVRANGEBYLEX
Item | Description |
---|---|
Syntax | EXZREVRANGEBYLEX <key> <max> <min> [LIMIT offset count] |
Time complexity | O(log(N)+M), where N indicates the number of elements in the TairZset key and M indicates
the number of elements returned.
Note When M is set to a constant, this expression can be regarded as O(log(N)). For example,
you can specify that the first 10 elements are always returned by using the LIMIT
offset count parameter.
|
Command description | Returns the elements whose scores are between the min value and the max value when
all elements of a key have the same score to ensure that elements are sorted in lexicographical
order.
Note This command is similar to EXZRANGEBYLEX except that this command sorts the results in reverse and places max in front of min.
|
Parameter |
|
Output | The elements whose values are within the specified range. |
Example |
Sample command:
Sample output:
|
EXZREM
Item | Description |
---|---|
Syntax | EXZREM key member [member ...] |
Time complexity | O(M*log(N)), where N indicates the number of elements in the TairZset key and M indicates the number of elements to be removed. |
Command description | Removes specified elements from a TairZset key. If the specified element does not
exist, the element is ignored.
Note If the key exists but its data structure is not TairZset, an error is returned.
|
Parameter | N/A |
Output | The number of elements removed from the key. The elements that do not exist are not included. |
Example |
Sample command:
Sample output:
|
EXZREMRANGEBYSCORE
Item | Description |
---|---|
Syntax | EXZREMRANGEBYSCORE key min max |
Time complexity | O(log(N)+M), where N indicates the number of elements in the TairZset key and M indicates the number of elements to be removed. |
Command description | Removes the elements from a TairZset key whose scores are greater than or equal to the min value and are less than or equal to the max value. |
Parameter | min and max: indicate the lowest score and the highest score. If multidimensional scores are
used, scores of each dimension are separated by a number sign (#).
Note
|
Output | The number of elements removed. |
Example |
Sample command:
Sample output:
|
EXZREMRANGEBYRANK
Item | Description |
---|---|
Syntax | EXZREMRANGEBYRANK key start stop |
Time complexity | O(log(N)+M), where N indicates the number of elements in the TairZset key and M indicates the number of elements to be removed. |
Command description | Removes the elements from a TairZset key whose ranks are within the range of the start value and the stop value. |
Parameter | Both start and stop indicate zero-based indexes. 0 indicates the element that has the lowest score. These indexes can be negative numbers. These numbers indicate offsets that start at the element that has the highest score. For example, -1 indicates the element that has the highest score, and -2 indicates element that has the second highest score. Other elements follow the same rule. |
Output | The number of elements removed. |
Example |
Sample command:
Sample output:
|
EXZREMRANGEBYLEX
Item | Description |
---|---|
Syntax | EXZREMRANGEBYLEX key min max |
Time complexity | O(log(N)+M), where N indicates the number of elements in the TairZset key and M indicates the number of elements to be removed. |
Command description | Removes the elements whose scores are between the min value and the max value when
all elements of a key have the same score to ensure that elements are sorted in lexicographical
order.
Note If you use the min and max parameters to specify the same range for the EXZREMRANGEBYLEX and EXZRANGEBYLEX commands, the elements removed by the EXZREMRANGEBYLEX command are the same as those
returned by the EXZRANGEBYLEX command.
|
Parameter | min and max: indicate the minimum and maximum string representation values of the element name.
You must specify the intervals of characters. The following section shows how to specify
intervals:
|
Output | The number of elements removed. |
Example |
Sample command:
Sample output:
|
EXZCARD
Item | Description |
---|---|
Syntax | EXZCARD key |
Time complexity | O(1) |
Command description | Returns the cardinality of a TairZset key. Cardinality indicates the number of elements in a key. |
Parameter | N/A |
Output | The number of elements in a TairZset key. If the key does not exist, 0 is returned. |
Example |
Sample command:
Sample output:
|
EXZRANK
Item | Description |
---|---|
Syntax | EXZRANK key member |
Time complexity | O(log(N)) |
Command description | Returns the rank of an element in a TairZset key. Ranks are sorted by score in ascending order. Ranks use a zero-based numbering scheme, and the rank of the element that has the lowest score is 0. Rank is also known as index. |
Parameter | N/A |
Output |
|
Example |
Sample command:
Sample output:
|
EXZREVRANK
Item | Description |
---|---|
Syntax | EXZREVRANK key member |
Time complexity | O(log(N)) |
Command description | Returns the rank of an element in a TairZset key. Ranks are sorted by score in descending
order. Ranks use a zero-based numbering scheme, and the rank of the element that has
the highest score is 0. Rank is also known as index.
Note This command is similar to EXZRANK except that this command sorts the results in reverse.
|
Parameter | N/A |
Output |
|
Example |
Sample command:
Sample output:
|
EXZCOUNT
Item | Description |
---|---|
Syntax | EXZCOUNT key min max |
Time complexity | O(log(N)), where N indicates the number of elements in the TairZset key.
Note This command uses element ranks to obtain the query range. Therefore, the workloads
associated with this command are not proportional to the size of the range.
|
Command description | Returns the number of elements in a TairZset key whose scores are between the min value and the max value. |
Parameter | min and max: indicate the lowest score and the highest score. If multidimensional scores are
used, scores of each dimension are separated by a number sign (#).
Note
|
Output | The integer number of elements within the specified score range. |
Example |
Sample command:
Sample output:
|
EXZLEXCOUNT
Item | Description |
---|---|
Syntax | EXZLEXCOUNT key min max |
Time complexity | O(log(N)), where N indicates the number of elements in the TairZset key.
Note This command uses element ranks to obtain the query range. Therefore, the workloads
associated with this command are not proportional to the size of the range.
|
Command description | Returns the elements whose scores are between the min value and the max value when
all elements of a key have the same score to ensure that elements are sorted in lexicographical
order.
Note
|
Parameter | min and max: indicate the minimum and maximum string representation values of the element name.
You must specify the intervals of characters. The following section shows how to specify
intervals:
|
Output | The integer number of elements within the specified score range. |
Example |
Sample command:
Sample output:
|
EXZRANKBYSCORE
Item | Description |
---|---|
Syntax | EXZRANKBYSCORE key score |
Time complexity | O(log(N)) |
Command description |
Calculates the rank of the specified element score in a TairZset key. Ranks are sorted
by score in ascending order. Ranks use a zero-based numbering scheme, and the rank
of the element that has the lowest score is 0. Rank is also known as index.
Note If the score does not exist, the estimated rank of the score in the key is returned.
If the score already exists, Tair ranks the score in front of other existing scores
in the key by default.
|
Parameter | N/A |
Output | The rank of the score in the key. |
Example |
Sample command:
Sample output:
|
EXZREVRANKBYSCORE
Item | Description |
---|---|
Syntax | EXZREVRANKBYSCORE key score |
Time complexity | O(log(N)) |
Command description |
Calculates the rank of the specified score in a TairZset key. Ranks are sorted by
score in descending order. Ranks use a zero-based numbering scheme, and the rank of
the element that has the highest score is 0. Rank is also known as index.
Note If the score does not exist, the estimated rank of the score in the key is returned.
If the score already exists, Tair ranks the score behind other existing scores in
the key by default.
|
Parameter | N/A |
Output | The rank of the score in the key. |
Example |
Sample command:
Sample output:
|