ZADD 

ZADD key [NX | XX] [GT | LT] [CH] [INCR] score member [score member
  ...]
Available since:
Redis Open Source 1.2.0
Time complexity:
O(log(N)) for each item added, where N is the number of elements in the sorted set.
ACL categories:
@write, @sortedset, @fast,
Compatibility:
Redis Software and Redis Cloud compatibility

Adds all the specified members with the specified scores to the sorted set stored at key. It is possible to specify multiple score / member pairs. If a specified member is already a member of the sorted set, the score is updated and the element reinserted at the right position to ensure the correct ordering.

If key does not exist, a new sorted set with the specified members as sole members is created, like if the sorted set was empty. If the key exists but does not hold a sorted set, an error is returned.

The score values should be the string representation of a double precision floating point number. +inf and -inf values are valid values as well.

Required arguments

key

The name of the key that holds the sorted set.

score member [score member ...]

One or more score-member pairs to add or update. score is a double-precision floating-point number.

Optional arguments

NX and XX are mutually exclusive, as are GT and LT.

NX

Only add new members; do not update existing members.

XX

Only update existing members; do not add new members.

GT

Only update an existing member if the new score is greater than the current score. Does not prevent adding new members.

LT

Only update an existing member if the new score is less than the current score. Does not prevent adding new members.

CH

Change the return value from the number of added members to the number of changed members (added plus updated).

INCR

Increment the member's score by score instead of setting it, behaving like ZINCRBY. Only one score-member pair may be given.

Examples

Foundational: Add one or more members to a sorted set with scores using ZADD (creates sorted set if needed, updates scores if member exists)
> ZADD myzset 1 "one"
(integer) 1
> ZADD myzset 1 "uno"
(integer) 1
> ZADD myzset 2 "two" 3 "three"
(integer) 2
> ZRANGE myzset 0 -1 WITHSCORES
1) "one"
2) "1"
3) "uno"
4) "1"
5) "two"
6) "2"
7) "three"
8) "3"
Redis CLI guide
Also, check out our other client tools Redis Insight and Redis for VS Code. 
res = r.zadd("myzset", {"one": 1})
print(res)
# >>> 1

res = r.zadd("myzset", {"uno": 1})
print(res)
# >>> 1

res = r.zadd("myzset", {"two": 2, "three": 3})
print(res)
# >>> 2

res = r.zrange("myzset", 0, -1, withscores=True)
# >>> [('one', 1.0), ('uno', 1.0), ('two', 2.0), ('three', 3.0)]
Python Quick-Start 
const val1 = await client.zAdd("myzset", [{ value: 'one', score: 1 }]);
console.log(val1);
// returns 1

const val2 = await client.zAdd("myzset", [{ value: 'uno', score: 1 }]);
console.log(val2);
// returns 1

const val3 = await client.zAdd("myzset", [{ value: 'two', score: 2 }, { value: 'three', score: 3 }]);
console.log(val3);
// returns 2

const val4 = await client.zRangeWithScores("myzset", 0, -1);
console.log(val4);
// returns [{value: 'one', score: 1}, {value: 'uno', score: 1}, {value: 'two', score: 2}, {value: 'three', score: 3} ]
Node.js Quick-Start 
        Map<String, Double> zAddExampleParams = new HashMap<>();
        zAddExampleParams.put("one", 1.0);
        long zAddResult1 = jedis.zadd("myzset", zAddExampleParams);
        System.out.println(zAddResult1);    // >>> 1

        zAddExampleParams.clear();
        zAddExampleParams.put("uno", 1.0);
        long zAddResult2 = jedis.zadd("myzset", zAddExampleParams);
        System.out.println(zAddResult2);    // >>> 1

        zAddExampleParams.clear();
        zAddExampleParams.put("two", 2.0);
        zAddExampleParams.put("three", 3.0);
        long zAddResult3 = jedis.zadd("myzset", zAddExampleParams);
        System.out.println(zAddResult3);    // >>> 2

        List<Tuple> zAddResult4 = jedis.zrangeWithScores("myzset", new ZRangeParams(0, -1));

        for (Tuple item: zAddResult4) {
            System.out.println("Element: " + item.getElement() + ", Score: " + item.getScore());
        }
        // >>> Element: one, Score: 1.0
        // >>> Element: uno, Score: 1.0
        // >>> Element: two, Score: 2.0
        // >>> Element: three, Score: 3.0
Java-Sync Quick-Start 
	zAddResult1, err := rdb.ZAdd(ctx, "myzset",
		redis.Z{Member: "one", Score: 1},
	).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(zAddResult1) // >>> 1

	zAddResult2, err := rdb.ZAdd(ctx, "myzset",
		redis.Z{Member: "uno", Score: 1},
	).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(zAddResult2)

	zAddResult3, err := rdb.ZAdd(ctx, "myzset",
		redis.Z{Member: "two", Score: 2},
		redis.Z{Member: "three", Score: 3},
	).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(zAddResult3) // >>> 2

	zAddResult4, err := rdb.ZRangeWithScores(ctx, "myzset", 0, -1).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(zAddResult4) // >>> [{1 one} {1 uno} {2 two} {3 three}]
Go Quick-Start 
        bool zAddResult1 = db.SortedSetAdd("myzset", "one", 1);
        Console.WriteLine(zAddResult1); // >>> True

        bool zAddResult2 = db.SortedSetAdd("myzset", "uno", 1);
        Console.WriteLine(zAddResult2); // >>> True

        long zAddResult3 = db.SortedSetAdd(
            "myzset",
            [
                new("two", 2),
                new("three", 3)
            ]
        );
        Console.WriteLine(zAddResult3); // >>> 2

        SortedSetEntry[] zAddResult4 = db.SortedSetRangeByRankWithScores("myzset", 0, -1);
        Console.WriteLine($"{string.Join(", ", zAddResult4.Select(b => $"{b.Element}: {b.Score}"))}");
        // >>> one: 1, uno: 1, two: 2, three: 3
C#-Sync (SE.Redis) Quick-Start

Give these commands a try in the interactive console:

ZADD myzset 1 "one" ZADD myzset 1 "uno" ZADD myzset 2 "two" 3 "three" ZRANGE myzset 0 -1 WITHSCORES

Details

Range of integer scores that can be expressed precisely

Redis sorted sets use a double 64-bit floating-point number to represent the score. This format precisely represents integers between -(2^53) and +(2^53), inclusive. In practical terms, you can store integers from -9007199254740992 to 9007199254740992 without losing precision. Redis represents larger integers and fractions in exponential form internally, so you may get only an approximation of the score you set.

Sorted sets 101

Sorted sets are sorted by their score in an ascending way. The same element only exists a single time, no repeated elements are permitted. The score can be modified both by ZADD that will update the element score, and as a side effect, its position on the sorted set, and by ZINCRBY that can be used in order to update the score relatively to its previous value.

The current score of an element can be retrieved using the ZSCORE command, that can also be used to verify if an element already exists or not.

For an introduction to sorted sets, see the data types page on sorted sets.

Elements with the same score

While the same element can't be repeated in a sorted set since every element is unique, it is possible to add multiple different elements having the same score. When multiple elements have the same score, they are ordered lexicographically (they are still ordered by score as a first key, however, locally, all the elements with the same score are relatively ordered lexicographically).

The lexicographic ordering used is binary, it compares strings as array of bytes.

If the user inserts all the elements in a sorted set with the same score (for example 0), all the elements of the sorted set are sorted lexicographically, and range queries on elements are possible using the command ZRANGEBYLEX (Note: it is also possible to query sorted sets by range of scores using ZRANGEBYSCORE).

Redis Software and Redis Cloud compatibility

Redis
Software		 Redis
Cloud		 Notes
✅ Standard
✅ Active-Active		 ✅ Standard
✅ Active-Active

Return information

Any of the following:

  • Nil reply: if the operation was aborted because of a conflict with one of the XX/NX/LT/GT options.
  • Integer reply: the number of new members when the CH option is not used.
  • Integer reply: the number of new or updated members when the CH option is used.
  • Bulk string reply: the updated score of the member when the INCR option is used.

History

  • Starting with Redis version 2.4.0: Accepts multiple elements.
  • Starting with Redis version 3.0.2: Added the XX, NX, CH and INCR options.
  • Starting with Redis version 6.2.0: Added the GT and LT options.
RATE THIS PAGE
Back to top ↑