{ "schema_version": 2, "id": "commands/zadd", "title": "ZADD", "url": "https://redis.io/docs/latest/commands/zadd/", "summary": "Adds one or more members to a sorted set, or updates their scores. Creates the key if it doesn't exist.", "since": "1.2.0", "tags": [ "docs", "develop", "stack", "oss", "rs", "rc", "oss", "kubernetes", "clients" ], "last_updated": "2026-09-18T09:48:43+01:00", "page_type": "content", "content_hash": "bc053a650c8e372f0cfd691e310dfe71d2eafa00f41fab0f584e33fd868409d2", "sections": [ { "id": "required-arguments", "title": "Required arguments", "role": "content", "text": "
key\n\nThe name of the key that holds the sorted set.\n\n
\n\n
score member [score member ...]\n\nOne or more score-member pairs to add or update. `score` is a double-precision floating-point number.\n\n
" }, { "id": "optional-arguments", "title": "Optional arguments", "role": "parameters", "text": "`NX` and `XX` are mutually exclusive, as are `GT` and `LT`.\n\n
NX\n\nOnly add new members; do not update existing members.\n\n
\n\n
XX\n\nOnly update existing members; do not add new members.\n\n
\n\n
GT\n\nOnly update an existing member if the new score is greater than the current score. Does not prevent adding new members.\n\n
\n\n
LT\n\nOnly update an existing member if the new score is less than the current score. Does not prevent adding new members.\n\n
\n\n
CH\n\nChange the return value from the number of added members to the number of changed members (added plus updated).\n\n
\n\n
INCR\n\nIncrement the member's score by `score` instead of setting it, behaving like `ZINCRBY`. Only one score-member pair may be given.\n\n
" }, { "id": "examples", "title": "Examples", "role": "example", "text": "Foundational: Add one or more members to a sorted set with scores using ZADD (creates sorted set if needed, updates scores if member exists)\n\n**Difficulty:** Beginner\n\n**Commands:** ZADD, ZRANGE\n\n**Complexity:**\n- ZADD: O(log(N)\n- ZRANGE: O(log(N)\n\n**Available in:** Redis CLI, C#, Go, Java (Asynchronous - Lettuce), Java (Reactive - Lettuce), Java (Synchronous - Jedis), JavaScript (Node.js), JavaScript (Node.js), PHP, Python, Ruby, Rust (Asynchronous), Rust (Synchronous)\n\n##### Redis CLI\n\n[code example]\n\n##### C#\n\n[code example]\n\n##### Go\n\n[code example]\n\n##### Java (Asynchronous - Lettuce)\n\n[code example]\n\n##### Java (Reactive - Lettuce)\n\n[code example]\n\n##### Java (Synchronous - Jedis)\n\n[code example]\n\n##### JavaScript (Node.js)\n\n[code example]\n\n##### JavaScript (Node.js)\n\n[code example]\n\n##### JavaScript (Node.js)\n\n[code example]\n\n##### JavaScript (Node.js)\n\n[code example]\n\n##### PHP\n\n[code example]\n\n##### Python\n\n[code example]\n\n##### Ruby\n\n[code example]\n\n##### Rust (Asynchronous)\n\n[code example]\n\n##### Rust (Synchronous)\n\n[code example]" }, { "id": "details", "title": "Details", "role": "content", "text": "" }, { "id": "range-of-integer-scores-that-can-be-expressed-precisely", "title": "Range of integer scores that can be expressed precisely", "role": "content", "text": "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." }, { "id": "sorted-sets-101", "title": "Sorted sets 101", "role": "content", "text": "Sorted sets are sorted by their score in an ascending way.\nThe same element only exists a single time, no repeated elements are\npermitted. The score can be modified both by `ZADD` that will update the\nelement score, and as a side effect, its position on the sorted set, and\nby [`ZINCRBY`](https://redis.io/docs/latest/commands/zincrby) that can be used in order to update the score relatively to its\nprevious value.\n\nThe current score of an element can be retrieved using the [`ZSCORE`](https://redis.io/docs/latest/commands/zscore) command,\nthat can also be used to verify if an element already exists or not.\n\nFor an introduction to sorted sets, see the data types page on [sorted\nsets](https://redis.io/docs/latest/develop/data-types#sorted-sets)." }, { "id": "elements-with-the-same-score", "title": "Elements with the same score", "role": "content", "text": "While the same element can't be repeated in a sorted set since every element\nis 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).\n\nThe lexicographic ordering used is binary, it compares strings as array of bytes.\n\nIf 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`](https://redis.io/docs/latest/commands/zrangebylex) (Note: it is also possible to query sorted sets by range of scores using [`ZRANGEBYSCORE`](https://redis.io/docs/latest/commands/zrangebyscore))." }, { "id": "redis-software-and-redis-cloud-compatibility", "title": "Redis Software and Redis Cloud compatibility", "role": "content", "text": "| Redis
Software | Redis
Cloud | Notes |\n|:----------------------|:-----------------|:------|\n| ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | |" }, { "id": "return-information", "title": "Return information", "role": "returns", "text": "**RESP2:**\n\nAny of the following:\n* [Nil reply](../../develop/reference/protocol-spec#bulk-strings): if the operation was aborted because of a conflict with one of the _XX/NX/LT/GT_ options.\n* [Integer reply](../../develop/reference/protocol-spec#integers): the number of new members when the _CH_ option is not used.\n* [Integer reply](../../develop/reference/protocol-spec#integers): the number of new or updated members when the _CH_ option is used.\n* [Bulk string reply](../../develop/reference/protocol-spec#bulk-strings): the updated score of the member when the _INCR_ option is used.\n\n**RESP3:**\n\nAny of the following:\n* [Null reply](../../develop/reference/protocol-spec#nulls): if the operation was aborted because of a conflict with one of the _XX/NX/LT/GT_ options.\n* [Integer reply](../../develop/reference/protocol-spec#integers): the number of new members when the _CH_ option is not used.\n* [Integer reply](../../develop/reference/protocol-spec#integers): the number of new or updated members when the _CH_ option is used.\n* [Double reply](../../develop/reference/protocol-spec#doubles): the updated score of the member when the _INCR_ option is used." } ], "examples": [ { "id": "examples-ex0", "language": "plaintext", "code": "> ZADD myzset 1 \"one\"\n(integer) 1\n> ZADD myzset 1 \"uno\"\n(integer) 1\n> ZADD myzset 2 \"two\" 3 \"three\"\n(integer) 2\n> ZRANGE myzset 0 -1 WITHSCORES\n1) \"one\"\n2) \"1\"\n3) \"uno\"\n4) \"1\"\n5) \"two\"\n6) \"2\"\n7) \"three\"\n8) \"3\"", "section_id": "examples" }, { "id": "examples-ex1", "language": "csharp", "code": "bool zAddResult1 = db.SortedSetAdd(\"myzset\", \"one\", 1);\n Console.WriteLine(zAddResult1); // >>> True\n\n bool zAddResult2 = db.SortedSetAdd(\"myzset\", \"uno\", 1);\n Console.WriteLine(zAddResult2); // >>> True\n\n long zAddResult3 = db.SortedSetAdd(\n \"myzset\",\n [\n new(\"two\", 2),\n new(\"three\", 3)\n ]\n );\n Console.WriteLine(zAddResult3); // >>> 2\n\n SortedSetEntry[] zAddResult4 = db.SortedSetRangeByRankWithScores(\"myzset\", 0, -1);\n Console.WriteLine($\"{string.Join(\", \", zAddResult4.Select(b => $\"{b.Element}: {b.Score}\"))}\");\n // >>> one: 1, uno: 1, two: 2, three: 3", "section_id": "examples" }, { "id": "examples-ex2", "language": "go", "code": "zAddResult1, err := rdb.ZAdd(ctx, \"myzset\",\n\t\tredis.Z{Member: \"one\", Score: 1},\n\t).Result()\n\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Println(zAddResult1) // >>> 1\n\n\tzAddResult2, err := rdb.ZAdd(ctx, \"myzset\",\n\t\tredis.Z{Member: \"uno\", Score: 1},\n\t).Result()\n\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Println(zAddResult2)\n\n\tzAddResult3, err := rdb.ZAdd(ctx, \"myzset\",\n\t\tredis.Z{Member: \"two\", Score: 2},\n\t\tredis.Z{Member: \"three\", Score: 3},\n\t).Result()\n\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Println(zAddResult3) // >>> 2\n\n\tzAddResult4, err := rdb.ZRangeWithScores(ctx, \"myzset\", 0, -1).Result()\n\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Println(zAddResult4) // >>> [{1 one} {1 uno} {2 two} {3 three}]", "section_id": "examples" }, { "id": "examples-ex3", "language": "java", "code": "CompletableFuture zAddExample = asyncCommands.zadd(\"myzset\", ScoredValue.just(1d, \"one\"))\n .thenCompose(res1 -> {\n System.out.println(res1); // >>> 1\n return asyncCommands.zadd(\"myzset\", ScoredValue.just(1d, \"uno\"));\n }).thenCompose(res2 -> {\n System.out.println(res2); // >>> 1\n return asyncCommands.zadd(\"myzset\",\n ScoredValue.just(2d, \"two\"), ScoredValue.just(3d, \"three\"));\n }).thenCompose(res3 -> {\n System.out.println(res3); // >>> 2\n return asyncCommands.zrangeWithScores(\"myzset\", 0, -1);\n }).thenAccept(res4 -> {\n System.out.println(res4);\n // >>> [ScoredValue[1.000000, one], ScoredValue[1.000000, uno],\n // >>> ScoredValue[2.000000, two], ScoredValue[3.000000, three]]\n }).toCompletableFuture();", "section_id": "examples" }, { "id": "examples-ex4", "language": "java", "code": "Mono zAddExample = reactiveCommands.zadd(\"myzset\", ScoredValue.just(1d, \"one\"))\n .doOnNext(res1 -> {\n System.out.println(res1); // >>> 1\n })\n .then(reactiveCommands.zadd(\"myzset\", ScoredValue.just(1d, \"uno\")))\n .doOnNext(res2 -> {\n System.out.println(res2); // >>> 1\n })\n .then(reactiveCommands.zadd(\"myzset\",\n ScoredValue.just(2d, \"two\"), ScoredValue.just(3d, \"three\")))\n .doOnNext(res3 -> {\n System.out.println(res3); // >>> 2\n })\n .then(reactiveCommands.zrangeWithScores(\"myzset\", 0, -1).collectList())\n .doOnNext(res4 -> {\n System.out.println(res4);\n // >>> [ScoredValue[1.000000, one], ScoredValue[1.000000, uno],\n // >>> ScoredValue[2.000000, two], ScoredValue[3.000000, three]]\n })\n .then();", "section_id": "examples" }, { "id": "examples-ex5", "language": "java", "code": "Map zAddExampleParams = new HashMap<>();\n zAddExampleParams.put(\"one\", 1.0);\n long zAddResult1 = jedis.zadd(\"myzset\", zAddExampleParams);\n System.out.println(zAddResult1); // >>> 1\n\n zAddExampleParams.clear();\n zAddExampleParams.put(\"uno\", 1.0);\n long zAddResult2 = jedis.zadd(\"myzset\", zAddExampleParams);\n System.out.println(zAddResult2); // >>> 1\n\n zAddExampleParams.clear();\n zAddExampleParams.put(\"two\", 2.0);\n zAddExampleParams.put(\"three\", 3.0);\n long zAddResult3 = jedis.zadd(\"myzset\", zAddExampleParams);\n System.out.println(zAddResult3); // >>> 2\n\n List zAddResult4 = jedis.zrangeWithScores(\"myzset\", new ZRangeParams(0, -1));\n\n for (Tuple item: zAddResult4) {\n System.out.println(\"Element: \" + item.getElement() + \", Score: \" + item.getScore());\n }\n // >>> Element: one, Score: 1.0\n // >>> Element: uno, Score: 1.0\n // >>> Element: two, Score: 2.0\n // >>> Element: three, Score: 3.0", "section_id": "examples" }, { "id": "examples-ex6", "language": "javascript", "code": "const val1 = await client.zAdd(\"myzset\", [{ value: 'one', score: 1 }]);\nconsole.log(val1);\n// returns 1\n\nconst val2 = await client.zAdd(\"myzset\", [{ value: 'uno', score: 1 }]);\nconsole.log(val2);\n// returns 1\n\nconst val3 = await client.zAdd(\"myzset\", [{ value: 'two', score: 2 }, { value: 'three', score: 3 }]);\nconsole.log(val3);\n// returns 2\n\nconst val4 = await client.zRangeWithScores(\"myzset\", 0, -1);\nconsole.log(val4);\n// returns [{value: 'one', score: 1}, {value: 'uno', score: 1}, {value: 'two', score: 2}, {value: 'three', score: 3} ]", "section_id": "examples" }, { "id": "examples-ex7", "language": "javascript", "code": "const res1 = await redis.zadd('myzset', 1, 'one');\nconsole.log(res1); // >>> 1\n\nconst res2 = await redis.zadd('myzset', 1, 'uno');\nconsole.log(res2); // >>> 1\n\nconst res3 = await redis.zadd('myzset', 2, 'two', 3, 'three');\nconsole.log(res3); // >>> 2\n\nconst res4 = await redis.zrange('myzset', 0, -1, 'WITHSCORES');\nconsole.log(res4); // >>> ['one', '1', 'uno', '1', 'two', '2', 'three', '3']", "section_id": "examples" }, { "id": "examples-ex8", "language": "javascript", "code": "const val1 = await client.zAdd(\"myzset\", [{ value: 'one', score: 1 }]);\nconsole.log(val1);\n// returns 1\n\nconst val2 = await client.zAdd(\"myzset\", [{ value: 'uno', score: 1 }]);\nconsole.log(val2);\n// returns 1\n\nconst val3 = await client.zAdd(\"myzset\", [{ value: 'two', score: 2 }, { value: 'three', score: 3 }]);\nconsole.log(val3);\n// returns 2\n\nconst val4 = await client.zRangeWithScores(\"myzset\", 0, -1);\nconsole.log(val4);\n// returns [{value: 'one', score: 1}, {value: 'uno', score: 1}, {value: 'two', score: 2}, {value: 'three', score: 3} ]", "section_id": "examples" }, { "id": "examples-ex9", "language": "javascript", "code": "const res1 = await redis.zadd('myzset', 1, 'one');\nconsole.log(res1); // >>> 1\n\nconst res2 = await redis.zadd('myzset', 1, 'uno');\nconsole.log(res2); // >>> 1\n\nconst res3 = await redis.zadd('myzset', 2, 'two', 3, 'three');\nconsole.log(res3); // >>> 2\n\nconst res4 = await redis.zrange('myzset', 0, -1, 'WITHSCORES');\nconsole.log(res4); // >>> ['one', '1', 'uno', '1', 'two', '2', 'three', '3']", "section_id": "examples" }, { "id": "examples-ex10", "language": "php", "code": "$res1 = $r->zadd('myzset', ['one' => 1]);\n echo $res1 . PHP_EOL; // >>> 1\n\n $res2 = $r->zadd('myzset', ['uno' => 1]);\n echo $res2 . PHP_EOL; // >>> 1\n\n $res3 = $r->zadd('myzset', ['two' => 2, 'three' => 3]);\n echo $res3 . PHP_EOL; // >>> 2\n\n $res4 = $r->zrange('myzset', 0, -1, ['withscores' => true]);\n echo json_encode($res4) . PHP_EOL;\n // >>> {\"one\":\"1\",\"uno\":\"1\",\"two\":\"2\",\"three\":\"3\"}", "section_id": "examples" }, { "id": "examples-ex11", "language": "python", "code": "res = r.zadd(\"myzset\", {\"one\": 1})\nprint(res)\n# >>> 1\n\nres = r.zadd(\"myzset\", {\"uno\": 1})\nprint(res)\n# >>> 1\n\nres = r.zadd(\"myzset\", {\"two\": 2, \"three\": 3})\nprint(res)\n# >>> 2\n\nres = r.zrange(\"myzset\", 0, -1, withscores=True)\n# >>> [('one', 1.0), ('uno', 1.0), ('two', 2.0), ('three', 3.0)]", "section_id": "examples" }, { "id": "examples-ex12", "language": "ruby", "code": "res1 = r.zadd('myzset', [[1, 'one']])\nputs res1 # >>> 1\n\nres2 = r.zadd('myzset', [[1, 'uno']])\nputs res2 # >>> 1\n\nres3 = r.zadd('myzset', [[2, 'two'], [3, 'three']])\nputs res3 # >>> 2\n\nres4 = r.zrange('myzset', 0, -1, with_scores: true)\nputs res4.inspect\n# >>> [[\"one\", 1.0], [\"uno\", 1.0], [\"two\", 2.0], [\"three\", 3.0]]", "section_id": "examples" }, { "id": "examples-ex13", "language": "rust", "code": "if let Ok(res1) = r.zadd(\"myzset\", \"one\", 1).await {\n let res1: i32 = res1;\n println!(\"{res1}\"); // >>> 1\n }\n\n if let Ok(res2) = r.zadd(\"myzset\", \"uno\", 1).await {\n let res2: i32 = res2;\n println!(\"{res2}\"); // >>> 1\n }\n\n if let Ok(res3) = r.zadd_multiple(\"myzset\", &[(2, \"two\"), (3, \"three\")]).await {\n let res3: i32 = res3;\n println!(\"{res3}\"); // >>> 2\n }\n\n if let Ok(res4) = r.zrange_withscores(\"myzset\", 0, -1).await {\n let res4: Vec<(String, f64)> = res4;\n println!(\"{res4:?}\");\n // >>> [(\"one\", 1.0), (\"uno\", 1.0), (\"two\", 2.0), (\"three\", 3.0)]\n }", "section_id": "examples" }, { "id": "examples-ex14", "language": "rust", "code": "if let Ok(res1) = r.zadd(\"myzset\", \"one\", 1) {\n let res1: i32 = res1;\n println!(\"{res1}\"); // >>> 1\n }\n\n if let Ok(res2) = r.zadd(\"myzset\", \"uno\", 1) {\n let res2: i32 = res2;\n println!(\"{res2}\"); // >>> 1\n }\n\n if let Ok(res3) = r.zadd_multiple(\"myzset\", &[(2, \"two\"), (3, \"three\")]) {\n let res3: i32 = res3;\n println!(\"{res3}\"); // >>> 2\n }\n\n if let Ok(res4) = r.zrange_withscores(\"myzset\", 0, -1) {\n let res4: Vec<(String, f64)> = res4;\n println!(\"{res4:?}\");\n // >>> [(\"one\", 1.0), (\"uno\", 1.0), (\"two\", 2.0), (\"three\", 3.0)]\n }", "section_id": "examples" } ] }