Tair (Redis® OSS-Compatible):exZset

Overview

Redis sorted sets support only a single score per member, which makes multi-dimension ranking difficult. Common workarounds (combining scores with IEEE 754 encoding or string concatenation) introduce precision loss, complex encoding/decoding logic, and the inability to atomically increment individual score dimensions.

TairZset solves this with a native multi-dimension data structure:

• Up to 256 score dimensions per member, formatted as score1#score2#...#scoreN

• Left-to-right priority: when comparing two members, the first dimension is compared first; if equal, the second dimension is compared, and so on

• Atomic increments: EXZINCRBY increments a specific dimension without read-modify-write cycles

• API compatibility: commands mirror native sorted set commands, requiring no encoding or decoding logic in your client

• Regular and distributed leaderboards: supports both single-node and distributed leaderboard architectures

• Open source TairJedis client: available at TairJedis SDK; use the open source code as a reference to implement clients for other languages

The module is open source at TairZset on GitHub.

Use cases

Multi-dimension scoring makes TairZset a natural fit for any leaderboard where a single metric is not enough:

• Live streaming leaderboards: rank streamers first by popularity, then by likes, then by gift amount — popularity#likes#gift_amount

• Medal standings: rank competitors by gold medals, then silver, then bronze — gold#silver#bronze

• Game leaderboards: rank players by score, then by task completion time, then by player rank — score#completion_time#player_rank

Prerequisites

Before you begin, ensure that you have:

• A Tair memory-optimized instance

• For memory-optimized instances compatible with Redis 5.0: minor version 1.7.1 or later

Update to the latest minor version for the most features and highest stability. See Update the minor version of an instance. For cluster instances or read/write splitting instances, also update the proxy nodes to ensure all commands run as expected.

Usage notes

• All TairZset commands operate on TairZset data in Tair instances. Running these commands on a key that holds a different data type returns an error.

• Score format consistency: all members in the same key must use the same number of score dimensions. Mixing 1#2#3 and 1#2 in the same key causes an error.

• Increment format: the increment in EXZINCRBY must match the score dimension format of the target member. To increment only one dimension of a three-dimension score, specify all three dimensions (e.g., EXZINCRBY key 0#1#0 member).

• +inf and -inf are valid score values in all score-range commands.

Quick start

The following example builds a two-dimension live streaming leaderboard: rank by popularity first, then by likes.

# Add streamers with initial scores (popularity#likes)
EXZADD leaderboard 1000#500 alice 800#900 bob 1000#300 carol

# Atomically increment alice's likes without a read-modify-write cycle
EXZINCRBY leaderboard 0#100 alice

# Get the full leaderboard, highest score first
EXZREVRANGE leaderboard 0 -1 WITHSCORES
# 1) "alice"
# 2) "1000#600"
# 3) "carol"
# 4) "1000#300"
# 5) "bob"
# 6) "800#900"

# Get alice's rank (highest = rank 0)
EXZREVRANK leaderboard alice
# (integer) 0

Commands

The following table lists all TairZset commands. Use the native Redis DEL command to delete TairZset keys.

Syntax conventions used in this topic:

• UPPERCASE KEYWORD: command keyword

• _italic_: variable

• [option]: optional parameter

• A|B: mutually exclusive options (choose one)

• ...: the preceding parameter can be repeated

EXZADD

Behavior:

• If the key does not exist, it is created.

• If a member does not exist, it is added with the given score.

• If a member already exists, its score is overwritten (unless NX is specified).

• Each score is a string representation of a double-precision floating-point number. +inf and -inf are valid values.

To use multi-dimension scoring, separate each dimension with #, for example 111#222#121. All members in the key must use the same number of dimensions.

Options:

Return value:

• Without options: the number of newly added members (members with only a score update are not counted)

• With CH: the number of members added or whose score changed

• With INCR: the member's new score as a string (e.g., "2#0#6"); returns nil if the operation is skipped due to NX or XX

Example:

EXZADD testkey NX 1#0#3 a 1#0#2 b
(integer) 2

EXZINCRBY

Behavior:

• If the key or member does not exist, both are created with the score set to increment.

• If the member exists, its score is incremented by increment.

• Each score dimension is a double-precision floating-point number. +inf and -inf are valid values.

• To decrement a score, pass a negative increment.

For multi-dimension scores, increment must use the same format as the member's score. For example, to increment only the second dimension of a three-dimension score, use 0#1#0.

Return value: The member's new score as a string. For multi-dimension scores, the format is "score1#score2#..." (e.g., "2#0#6").

Example:

EXZINCRBY testkey 2#2#1 a
"3#2#4"

EXZSCORE

Return value: The member's score as a string. For multi-dimension scores, the format is "score1#score2#..." (e.g., "3#2#4").

Example:

EXZSCORE testkey a
"3#2#4"

EXZRANGE

Options:

Return value: A list of members within the specified range, with scores if WITHSCORES is specified.

Example:

EXZRANGE testkey 0 -1 WITHSCORES
1) "b"
2) "1#0#2"
3) "a"
4) "3#2#4"

EXZREVRANGE

Options:

Return value: A list of members within the specified range, with scores if WITHSCORES is specified.

Example:

EXZREVRANGE testkey 0 -1 WITHSCORES
1) "a"
2) "3#2#4"
3) "b"
4) "1#0#2"

EXZRANGEBYSCORE

Options:

Return value: A list of members within the score range, with scores if WITHSCORES is specified.

Example:

EXZRANGEBYSCORE testkey 0#0#0 6#6#6 WITHSCORES
1) "b"
2) "1#0#2"
3) "a"
4) "3#2#4"

EXZREVRANGEBYSCORE

Options:

Return value: A list of members within the score range, with scores if WITHSCORES is specified.

Example:

EXZREVRANGEBYSCORE testkey 6#6#6 0#0#0 WITHSCORES
1) "a"
2) "3#2#4"
3) "b"
4) "1#0#2"

EXZRANGEBYLEX

If members have different scores, the returned set is undefined. Lexicographic comparison uses the C memcmp() function, comparing bytes one at a time. If two strings share a common prefix, the longer string ranks higher.

Options:

Return value: A list of members within the lexicographic range.

Example:

EXZRANGEBYLEX zzz [a [b
1) "aba"
2) "abc"

EXZREVRANGEBYLEX

Options:

Return value: A list of members within the lexicographic range, in reverse order.

Example:

EXZREVRANGEBYLEX zzz [b [a
1) "abc"
2) "aba"

EXZREM

Return value: The number of members removed (not counting non-existent members).

Example:

EXZREM testkey a
(integer) 1

EXZREMRANGEBYSCORE

Options:

Return value: The number of members removed.

Example:

EXZREMRANGEBYSCORE testkey 3#2#4 6#6#6
(integer) 1

EXZREMRANGEBYRANK

Options:

Return value: The number of members removed.

Example:

EXZREMRANGEBYRANK testkey 0 1
(integer) 1

EXZREMRANGEBYLEX

Options:

Return value: The number of members removed.

Example:

EXZREMRANGEBYLEX testkey [a [b
(integer) 2

EXZCARD

Return value: The number of members (integer).

Example:

EXZCARD testkey
(integer) 2

EXZRANK

Return value:

• The member's rank (integer) if the member exists

• nil if the key or member does not exist

Example:

EXZRANK testkey b
(integer) 0

EXZREVRANK

Return value:

• The member's rank (integer) if the member exists

• nil if the key or member does not exist

Example:

EXZREVRANK testkey b
(integer) 1

EXZCOUNT

Options:

Return value: The number of members within the score range (integer).

Example:

EXZCOUNT testkey (1#0#2 6#6#6
(integer) 1

EXZLEXCOUNT

If members have different scores, the result is undefined. Lexicographic comparison uses the C memcmp() function. If two strings share a common prefix, the longer string ranks higher.

Options:

Return value: The number of members within the lexicographic range (integer).

Example:

EXZLEXCOUNT zzz [a [b
(integer) 2

EXZRANKBYSCORE

Return value: The rank of the specified score (integer).

Example:

EXZRANKBYSCORE testkey 2#0#2
(integer) 1

EXZREVRANKBYSCORE

Return value: The rank of the specified score (integer).

Example:

EXZREVRANKBYSCORE testkey 2#0#2
(integer) 1

What's next

• Easily implement multi-dimension leaderboards using exZset

• Implement distributed architecture leaderboards using exZset