ZADD

语法

ZADD key [NX | XX] [GT | LT] [CH] [INCR] score member [score member
  ...]

可用版本: Redis 开源版 1.2.0
时间复杂度: 添加的每个元素的复杂度为 O(log(N))，其中 N 是有序集合中的元素数量。
ACL 类别: @write, @sortedset, @fast,

将所有指定成员及指定分值添加到存储在 key 中的有序集合中。可以指定多个分值/成员对。如果指定成员已经是有序集合的成员，则会更新其分值并将该元素重新插入到正确的位置，以确保排序正确。

如果 key 不存在，则会创建一个新的有序集合，并将指定成员作为唯一的成员，就像有序集合为空时一样。如果 key 存在但不是有序集合，则返回错误。

分值应为双精度浮点数的字符串表示。+inf 和 -inf 也是有效值。

ZADD 选项

ZADD 支持一系列选项，这些选项在键名之后、第一个分值参数之前指定。选项包括：

XX: 只更新已存在的元素。不添加新元素。
NX: 只添加新元素。不更新已存在的元素。
LT: 仅在新的分值小于当前分值时更新现有元素。此标志不阻止添加新元素。
GT: 仅在新的分值大于当前分值时更新现有元素。此标志不阻止添加新元素。
CH: 将返回值从添加的新元素数量修改为更改的元素总数（CH 是 changed 的缩写）。更改的元素包括添加的新元素和分值已更新的现有元素。因此，命令行中指定但分值与之前相同的元素不计算在内。注意：通常 ZADD 的返回值只计算添加的新元素数量。
INCR: 指定此选项时，ZADD 的行为类似于 ZINCRBY。在此模式下只能指定一对分值-元素。

注意：GT、LT 和 NX 选项互斥。

可精确表示的整数分值范围

Redis 有序集合使用双精度 64 位浮点数来表示分值。在我们支持的所有架构中，这都表示为 IEEE 754 浮点数，它可以精确表示介于 -(2^53) 和 +(2^53) 之间的整数（包括这两个值）。更实际地说，介于 -9007199254740992 和 9007199254740992 之间的所有整数都可以完美表示。较大的整数或小数部分在内部以指数形式表示，因此您设置的分值（小数或非常大的整数）可能只能得到一个近似值。

有序集合基础知识

有序集合按分值升序排序。同一元素只能存在一次，不允许重复元素。分值可以通过 ZADD 进行修改（它会更新元素分值，并因此改变其在有序集合中的位置），也可以通过 ZINCRBY 进行修改（它用于相对于前一个值更新分值）。

可以使用 ZSCORE 命令检索元素的当前分值，该命令也可用于验证元素是否存在。

有关有序集合的介绍，请参阅数据类型页面上的有序集合部分。

具有相同分值的元素

虽然同一个元素不能在有序集合中重复出现（因为每个元素都是唯一的），但可以添加具有相同分值的多个不同元素。当多个元素具有相同分值时，它们会按字典顺序排序（它们仍然首先按分值排序，但在局部，所有分值相同的元素会按字典顺序相对排序）。

使用的字典顺序是二进制的，它将字符串作为字节数组进行比较。

如果用户将所有元素以相同分值（例如 0）插入有序集合，则有序集合中的所有元素都会按字典顺序排序，并且可以使用命令 ZRANGEBYLEX 对元素执行范围查询（注意：也可以使用 ZRANGEBYSCORE 按分值范围查询有序集合）。

示例

>_ Redis CLI

> 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"

Python

import redis

r = redis.Redis(host="localhost", port=6379, db=0, decode_responses=True)

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)]


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

res = r.zrange("myzset", 0, -1)
print(res)
# >>> ['one', 'two', 'three']

res = r.zrange("myzset", 2, 3)
print(res)
# >>> ['three']

res = r.zrange("myzset", -2, -1)
print(res)
# >>> ['two', 'three']

res = r.zadd("myzset", {"one": 1, "two":2, "three":3})
res = r.zrange("myzset", 0, 1, withscores=True)
print(res)
# >>> [('one', 1.0), ('two', 2.0)]

res = r.zadd("myzset", {"one": 1, "two":2, "three":3})
res = r.zrange("myzset", 2, 3, byscore=True, offset=1, num=1)
print(res)
# >>> ['three']

Node.js


import { createClient } from 'redis';

const client = createClient();
client.on('error', err => console.log('Redis Client Error', err));
await client.connect().catch(console.error);

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} ]


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

const val6 = await client.zRange('myzset', 0, -1);
console.log(val6);
// returns ['one', 'two', 'three']

const val7 = await client.zRange('myzset', 2, 3);
console.log(val7);
// returns ['three']

const val8 = await client.zRange('myzset', -2, -1);
console.log(val8);
// returns ['two', 'three']

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

const val10 = await client.zRangeWithScores('myzset', 0, 1);
console.log(val10);
// returns [{value: 'one', score: 1}, {value: 'two', score: 2}]

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

const val12 = await client.zRange('myzset', 2, 3, { BY: 'SCORE', LIMIT: { offset: 1, count: 1 } });
console.log(val12);
// >>> ['three']

await client.quit();

Java-Sync


import java.util.HashMap;
import java.util.Map;
import java.util.List;
import redis.clients.jedis.UnifiedJedis;
import redis.clients.jedis.params.ZRangeParams;
import redis.clients.jedis.resps.Tuple;

import static org.junit.jupiter.api.Assertions.assertEquals;

public class CmdsSortedSetExample {

    public void run() {
        UnifiedJedis jedis = new UnifiedJedis("redis://localhost:6379");





        // Tests for 'bzmpop' step.




        // Tests for 'bzpopmax' step.




        // Tests for 'bzpopmin' step.


        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

        // Tests for 'zadd' step.




        // Tests for 'zcard' step.




        // Tests for 'zcount' step.




        // Tests for 'zdiff' step.




        // Tests for 'zdiffstore' step.




        // Tests for 'zincrby' step.




        // Tests for 'zinter' step.




        // Tests for 'zintercard' step.




        // Tests for 'zinterstore' step.




        // Tests for 'zlexcount' step.




        // Tests for 'zmpop' step.




        // Tests for 'zmscore' step.




        // Tests for 'zpopmax' step.




        // Tests for 'zpopmin' step.




        // Tests for 'zrandmember' step.


        Map<String, Double> zRangeExampleParams1 = new HashMap<>();
        zRangeExampleParams1.put("one", 1.0);
        zRangeExampleParams1.put("two", 2.0);
        zRangeExampleParams1.put("three", 3.0);
        long zRangeResult1 = jedis.zadd("myzset", zRangeExampleParams1);
        System.out.println(zRangeResult1);  // >>> 3

        List<String> zRangeResult2 = jedis.zrange("myzset", new ZRangeParams(0, -1));
        System.out.println(String.join(", ", zRangeResult2));   // >>> one, two, three

        List<String> zRangeResult3 = jedis.zrange("myzset", new ZRangeParams(2, 3));
        System.out.println(String.join(", ", zRangeResult3));   // >> three

        List<String> zRangeResult4 = jedis.zrange("myzset", new ZRangeParams(-2, -1));
        System.out.println(String.join(", ", zRangeResult4));   // >> two, three

        // Tests for 'zrange1' step.


        Map<String, Double> zRangeExampleParams2 = new HashMap<>();
        zRangeExampleParams2.put("one", 1.0);
        zRangeExampleParams2.put("two", 2.0);
        zRangeExampleParams2.put("three", 3.0);
        long zRangeResult5 = jedis.zadd("myzset", zRangeExampleParams2);
        System.out.println(zRangeResult5);  // >>> 3

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

        for (Tuple item: zRangeResult6) {
            System.out.println("Element: " + item.getElement() + ", Score: " + item.getScore());
        }
        // >>> Element: one, Score: 1.0
        // >>> Element: two, Score: 2.0

        // Tests for 'zrange2' step.


        Map<String, Double> zRangeExampleParams3 = new HashMap<>();
        zRangeExampleParams3.put("one", 1.0);
        zRangeExampleParams3.put("two", 2.0);
        zRangeExampleParams3.put("three", 3.0);
        long zRangeResult7 = jedis.zadd("myzset", zRangeExampleParams3);
        System.out.println(zRangeResult7);  // >>> 3

        List<String> zRangeResult8 = jedis.zrangeByScore("myzset", "(1", "+inf", 1, 1);
        System.out.println(String.join(", ", zRangeResult8));   // >>> three

        // Tests for 'zrange3' step.




        // Tests for 'zrangebylex' step.




        // Tests for 'zrangebyscore' step.




        // Tests for 'zrangestore' step.




        // Tests for 'zrank' step.




        // Tests for 'zrem' step.




        // Tests for 'zremrangebylex' step.




        // Tests for 'zremrangebyrank' step.




        // Tests for 'zremrangebyscore' step.




        // Tests for 'zrevrange' step.




        // Tests for 'zrevrangebylex' step.




        // Tests for 'zrevrangebyscore' step.




        // Tests for 'zrevrank' step.




        // Tests for 'zscan' step.




        // Tests for 'zscore' step.




        // Tests for 'zunion' step.




        // Tests for 'zunionstore' step.


        jedis.close();
    }
}

package example_commands_test

import (
	"context"
	"fmt"

	"github.com/redis/go-redis/v9"
)


func ExampleClient_zadd_cmd() {
	ctx := context.Background()

	rdb := redis.NewClient(&redis.Options{
		Addr:     "localhost:6379",
		Password: "", // no password docs
		DB:       0,  // use default DB
	})


	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}]

}

func ExampleClient_zrange1() {
	ctx := context.Background()

	rdb := redis.NewClient(&redis.Options{
		Addr:     "localhost:6379",
		Password: "", // no password docs
		DB:       0,  // use default DB
	})


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

	if err != nil {
		panic(err)
	}

	fmt.Println(zrangeResult1) // >>> 3

	zrangeResult2, err := rdb.ZRange(ctx, "myzset", 0, -1).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(zrangeResult2) // >>> [one two three]

	zrangeResult3, err := rdb.ZRange(ctx, "myzset", 2, 3).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(zrangeResult3) // >>> [three]

	zrangeResult4, err := rdb.ZRange(ctx, "myzset", -2, -1).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(zrangeResult4) // >>> [two three]

}

func ExampleClient_zrange2() {
	ctx := context.Background()

	rdb := redis.NewClient(&redis.Options{
		Addr:     "localhost:6379",
		Password: "", // no password docs
		DB:       0,  // use default DB
	})


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

	if err != nil {
		panic(err)
	}

	fmt.Println(zRangeResult5) // >>> 3

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

	if err != nil {
		panic(err)
	}

	fmt.Println(zRangeResult6) // >>> [{1 one} {2 two}]

}

func ExampleClient_zrange3() {
	ctx := context.Background()

	rdb := redis.NewClient(&redis.Options{
		Addr:     "localhost:6379",
		Password: "", // no password docs
		DB:       0,  // use default DB
	})


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

	if err != nil {
		panic(err)
	}

	fmt.Println(zRangeResult7) // >>> 3

	zRangeResult8, err := rdb.ZRangeArgs(ctx,
		redis.ZRangeArgs{
			Key:     "myzset",
			ByScore: true,
			Start:   "(1",
			Stop:    "+inf",
			Offset:  1,
			Count:   1,
		},
	).Result()

	if err != nil {
		panic(err)
	}

	fmt.Println(zRangeResult8) // >>> [three]

}


using NRedisStack.Tests;
using StackExchange.Redis;



public class CmdsSortedSet
{
    public void run()
    {
        var muxer = ConnectionMultiplexer.Connect("localhost:6379");
        var db = muxer.GetDatabase();




        // Tests for 'bzmpop' step.




        // Tests for 'bzpopmax' step.




        // Tests for 'bzpopmin' step.


        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 SortedSetEntry[] {
                new SortedSetEntry("two", 2),
                new SortedSetEntry("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

        // Tests for 'zadd' step.




        // Tests for 'zcard' step.




        // Tests for 'zcount' step.




        // Tests for 'zdiff' step.




        // Tests for 'zdiffstore' step.




        // Tests for 'zincrby' step.




        // Tests for 'zinter' step.




        // Tests for 'zintercard' step.




        // Tests for 'zinterstore' step.




        // Tests for 'zlexcount' step.




        // Tests for 'zmpop' step.




        // Tests for 'zmscore' step.




        // Tests for 'zpopmax' step.




        // Tests for 'zpopmin' step.




        // Tests for 'zrandmember' step.


        long zRangeResult1 = db.SortedSetAdd(
            "myzset",
            new SortedSetEntry[] {
                new SortedSetEntry("one", 1),
                new SortedSetEntry("two", 2),
                new SortedSetEntry("three", 3)
            }
        );
        Console.WriteLine(zRangeResult1);   // >>> 3

        RedisValue[] zRangeResult2 = db.SortedSetRangeByRank("myzset", 0, -1);
        Console.WriteLine(string.Join(", ", zRangeResult2));
        // >>> one, two, three

        RedisValue[] zRangeResult3 = db.SortedSetRangeByRank("myzset", 2, 3);
        Console.WriteLine(string.Join(", ", zRangeResult3));
        // >>> three

        RedisValue[] zRangeResult4 = db.SortedSetRangeByRank("myzset", -2, -1);
        Console.WriteLine(string.Join(", ", zRangeResult4));
        // >>> two, three

        // Tests for 'zrange1' step.


        long zRangeResult5 = db.SortedSetAdd(
            "myzset",
            new SortedSetEntry[] {
                new SortedSetEntry("one", 1),
                new SortedSetEntry("two", 2),
                new SortedSetEntry("three", 3)
            }
        );

        SortedSetEntry[] zRangeResult6 = db.SortedSetRangeByRankWithScores("myzset", 0, 1);
        Console.WriteLine($"{string.Join(", ", zRangeResult6.Select(b => $"{b.Element}: {b.Score}"))}");
        // >>> one: 1, two: 2

        // Tests for 'zrange2' step.


        long zRangeResult7 = db.SortedSetAdd(
            "myzset",
            new SortedSetEntry[] {
                new SortedSetEntry("one", 1),
                new SortedSetEntry("two", 2),
                new SortedSetEntry("three", 3)
            }
        );

        RedisValue[] zRangeResult8 = db.SortedSetRangeByScore(
            "myzset",
            1,
            double.PositiveInfinity,
            Exclude.Start,
            skip: 1, take: 1
        );
        Console.WriteLine(string.Join(", ", zRangeResult8));
        // >>> three

        // Tests for 'zrange3' step.




        // Tests for 'zrangebylex' step.




        // Tests for 'zrangebyscore' step.




        // Tests for 'zrangestore' step.




        // Tests for 'zrank' step.




        // Tests for 'zrem' step.




        // Tests for 'zremrangebylex' step.




        // Tests for 'zremrangebyrank' step.




        // Tests for 'zremrangebyscore' step.




        // Tests for 'zrevrange' step.




        // Tests for 'zrevrangebylex' step.




        // Tests for 'zrevrangebyscore' step.




        // Tests for 'zrevrank' step.




        // Tests for 'zscan' step.




        // Tests for 'zscore' step.




        // Tests for 'zunion' step.




        // Tests for 'zunionstore' step.


    }
}

在交互式控制台中试试这些命令

RESP2 回复

以下任意一种

Nil 回复：如果由于与 XX/NX/LT/GT 选项之一冲突而中止操作。
Integer 回复：未使用 CH 选项时新增成员的数量。
Integer 回复：使用 CH 选项时新增或更新成员的数量。
Bulk string 回复：使用 INCR 选项时成员的更新分值。

RESP3 回复