Options
All
  • Public
  • Public/Protected
  • All
Menu

Class RedisSortedSetClient

对于排序集 myzset { a: '2', c: '4.5' }

  • key 指整个排序集在 Redis 中存储的名称。如:myzset。
  • zset, 排序集 表示 Sorted Set。
  • member, 成员, element, 元素 表示排序集内的元素名称。如:a, c。
  • score, 分数 表示排序集内元素对应的分数。如:2, 4.5。

Hierarchy

Index

Constructors

constructor

Connection Methods

echo

  • echo(message: string): Promise<string>
  • 直接返回 msg 本身。

    例子:

    await client.echo('Hello World!')
    // "Hello World!"
    

    Parameters

    • message: string

    Returns Promise<string>

ping

  • ping(msg?: string): Promise<string>
  • 如果没有提供参数返回 PONG。否则返回 msg 本身。

    例子:

    await client.ping()
    // "PONG"
    await client.ping('Hello World!')
    // "Hello World!"
    

    Parameters

    • Optional msg: string

      需要发送的信息,

    Returns Promise<string>

quit

  • quit(): Promise<"OK">
  • 请求 Redis server 关闭连接。

    • Redis Server 会在前面的命令都处理完后立刻关闭连接。

    始终返回 OK。

    Returns Promise<"OK">

select

  • select(db: number): Promise<string>
    • 起始版本:1.0.0

    选择从 0 开始计数的 Redis 逻辑数据库。

    Redis 的可选数据库是一种命名空间格式。所有的数据仍然存在相同的 RDB / AOF 文件中。不同的数据库可以有相同的 key。
    FLUSHDB [[RedisClient.swapdb | SWAPDB]] RANDOMKEY 可以在指定的数据库工作。

    Parameters

    • db: number

    Returns Promise<string>

    查看原始定义

Other Methods

on

  • Parameters

    • event: string | symbol
    • listener: (...args: any[]) => void
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns RedisSortedSetClient

once

  • Parameters

    • event: string | symbol
    • listener: (...args: any[]) => void
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns RedisSortedSetClient

Server Methods

info

  • info(section?: "server" | "clients" | "memory" | "persistence" | "stats" | "replication" | "cpu" | "commandstats" | "cluster" | "keyspace" | "all" | "defaultƒ"): Promise<RedisServerInfo>

Sorted Set Methods

bzpopmax

  • bzpopmax(keys: [string | Buffer, ...(string | Buffer)[]], timeout: number): Promise<KeyMemberScore>
  • BZPOPMAX 是阻塞版本的 ZPOPMAX 命令。
    当指定的排序集中没有可弹出元素时会阻塞连接,直到有其他客户端向排序集中插入元素,或者超时。

    • 没有元素可弹出且超时,返回 null。
    • 指定的排序集中有可以弹出的元素时,返回形如 key,member,score 的三元组。

    更准确的语义请参考 BLPOP 命令。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3, four: 4 })
    // 4
    await client.bzpopmax(['zset', 'zset1'], 0)
    // ["zset", "four", "4"]
    

    Parameters

    • keys: [string | Buffer, ...(string | Buffer)[]]
    • timeout: number

      超时时间,单位秒。6.0 版本开始支持双精度浮点数表示,更早的版本只支持整数。

    Returns Promise<KeyMemberScore>

bzpopmin

  • bzpopmin(keys: [string | Buffer, ...(string | Buffer)[]], timeout: number): Promise<KeyMemberScore>
  • BZPOPMAX 是阻塞版本的 ZPOPMIN 命令。
    当指定的排序集中没有可弹出元素时会阻塞连接,直到有其他客户端向排序集中插入元素,或者超时。

    • 没有元素可弹出且超时,返回 null。
    • 指定的排序集中有可以弹出的元素时,返回形如 key,member,score 的三元组。

    更准确的语义请参考 BLPOP 命令。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3, four: 4 })
    // 4
    await client.bzpopmin(['zset', 'zset1'], 0)
    // ["zset", "one", "1"]
    

    Parameters

    • keys: [string | Buffer, ...(string | Buffer)[]]
    • timeout: number

      超时时间,单位秒。6.0 版本开始支持双精度浮点数表示,更早的版本只支持整数。

    Returns Promise<KeyMemberScore>

zadd

    • Redis官方文档https://redis.io/commands/zadd
    • 起始版本:1.2.0
    • 时间复杂度:每添加一个 item 的复杂度是 O(log(N)),N 是 zset 包含的元素

    将指定的 score/member 对添加到 key 对应的 zset 中。可以指定多个 score/member 对。
    如果指定的 member 已经存在于 zset 中,则将更新 score 并在正确的位置重新插入 member,以确保顺序正确。

    • 如果 key 不存在,则会创建一个以指定 member 为唯一 member 的新 zset,就像该 zset 为空一样。
    • 如果 key 存在对应的值不是 zset,则返回错误。
    • score 值应为双精度浮点数的字符串表示形式。+inf-inf 也是有效值。

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

    Redis zset 使用 IEEE 754 64 位双精度浮点数 表示 score。
    它能表示的整数范围是 [-(2^53), +(2^53)]。确切的说就是 [-9007199254740992, 9007199254740992]。
    较大的整数或小数在内部以指数形式表示,因此只能获得十进制数字的近似值。

    排序集

    Redis zset 以 score 正序进行存储。相同的 member 只能存在一次,不允许出现重复的 member。
    score 可以通过 ZADD 命令进行修改,它会更新 score,同时更新对应的 member 在排序集中的位置。

    分数相同的 member

    虽然排序集中 member 不可以重复,但是不同的 member 可以对应相同的 score。
    当多个 member 对应相同的 score 时,它们会按照 字典序 进行排列。
    字典序的意思是将字符串看作一个二进制数组,从头进行比较。
    如果用户向一个排序集中以相同的分数(比如 0)插入所有 member,则这个排序集中的所有 member 按照字典序排列。
    此时范围查询可以使用 ZRANGEBYLEX 命令。

    返回值

    • 不使用 incr_mode 的时候,返回整数,表示被添加的 member 数量。此时使用 CH 选项,则返回值表示被修改的 member 数量。
    • 使用 incr_mode=true 则会将命令行为变为自增模式,此时只能接受一对 score/member,并返回修改后的 score。
      • 当同时传递了 update_if_member: 'NX' | 'XX' 的时候,如果命令被终止则会返回 null。
      • 注意:6.2 版本新添加的 update_if_score: 'LT' | 'GT' 选项(对应 Redis 命令的 LT|GT 选项)行为有些特殊。
        这个选项在不符合条件时会阻止修改 score。但是依然会返回修改后的 score。
        比如:
        对于排序集 zset { a: '12' }
        对 member a 执行自增操作,但是仅相当新结果小于旧结果时进行修改,
        await client.zadd('zset', {a: '1'}, true, { update_if_score: 'LT' })
        此时返回 '13',即执行了自增之后的结果,但实际上排序集的状态为 zset { a: '12' },也就是没被修改。

    例子:

    await client.sadd('myset', 'Hello')
    // 1
    await client.sadd('myset', 'World')
    // 1
    await client.sadd('myset', 'World')
    // 0
    await client.smembers('myset')
    // ["World", "Hello"]
    

    Type parameters

    • T: {}

    Parameters

    • key: string | Buffer
    • member_score_pair: NonEmptyObject<T>

      2.4 版本开始支持多组 member/score,更早的版本只能传递一组 member/score。

    • Optional options: ZaddOptions

    Returns Promise<number>

    • Redis官方文档https://redis.io/commands/zadd
    • 起始版本:1.2.0
    • 时间复杂度:每添加一个 item 的复杂度是 O(log(N)),N 是 zset 包含的元素

    将指定的 score/member 对添加到 key 对应的 zset 中。可以指定多个 score/member 对。
    如果指定的 member 已经存在于 zset 中,则将更新 score 并在正确的位置重新插入 member,以确保顺序正确。

    • 如果 key 不存在,则会创建一个以指定 member 为唯一 member 的新 zset,就像该 zset 为空一样。
    • 如果 key 存在对应的值不是 zset,则返回错误。
    • score 值应为双精度浮点数的字符串表示形式。+inf-inf 也是有效值。

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

    Redis zset 使用 IEEE 754 64 位双精度浮点数 表示 score。
    它能表示的整数范围是 [-(2^53), +(2^53)]。确切的说就是 [-9007199254740992, 9007199254740992]。
    较大的整数或小数在内部以指数形式表示,因此只能获得十进制数字的近似值。

    排序集

    Redis zset 以 score 正序进行存储。相同的 member 只能存在一次,不允许出现重复的 member。
    score 可以通过 ZADD 命令进行修改,它会更新 score,同时更新对应的 member 在排序集中的位置。

    分数相同的 member

    虽然排序集中 member 不可以重复,但是不同的 member 可以对应相同的 score。
    当多个 member 对应相同的 score 时,它们会按照 字典序 进行排列。
    字典序的意思是将字符串看作一个二进制数组,从头进行比较。
    如果用户向一个排序集中以相同的分数(比如 0)插入所有 member,则这个排序集中的所有 member 按照字典序排列。
    此时范围查询可以使用 ZRANGEBYLEX 命令。

    返回值

    • 不使用 incr_mode 的时候,返回整数,表示被添加的 member 数量。此时使用 CH 选项,则返回值表示被修改的 member 数量。
    • 使用 incr_mode=true 则会将命令行为变为自增模式,此时只能接受一对 score/member,并返回修改后的 score。
      • 当同时传递了 update_if_member: 'NX' | 'XX' 的时候,如果命令被终止则会返回 null。
      • 注意:6.2 版本新添加的 update_if_score: 'LT' | 'GT' 选项(对应 Redis 命令的 LT|GT 选项)行为有些特殊。
        这个选项在不符合条件时会阻止修改 score。但是依然会返回修改后的 score。
        比如:
        对于排序集 zset { a: '12' }
        对 member a 执行自增操作,但是仅相当新结果小于旧结果时进行修改,
        await client.zadd('zset', {a: '1'}, true, { update_if_score: 'LT' })
        此时返回 '13',即执行了自增之后的结果,但实际上排序集的状态为 zset { a: '12' },也就是没被修改。

    例子:

    await client.sadd('myset', 'Hello')
    // 1
    await client.sadd('myset', 'World')
    // 1
    await client.sadd('myset', 'World')
    // 0
    await client.smembers('myset')
    // ["World", "Hello"]
    

    Type parameters

    • T: {}

    Parameters

    • key: string | Buffer
    • member_score_pair: NonEmptyObject<T>

      2.4 版本开始支持多组 member/score,更早的版本只能传递一组 member/score。

    • incr_mode: true

      自增模式,3.0.2 版本开始可用。

    • Optional options: ZaddOptions

    Returns Promise<null | `${number}`>

zcard

  • zcard(key: string | Buffer): Promise<number>
  • 返回排序集的成员总数量。当 key 不存在时返回 0。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3, four: 4 })
    // 4
    await client.zcard('zset')
    // 4
    

    Parameters

    • key: string | Buffer

    Returns Promise<number>

zcount

  • 返回排序集中 score 在 min 和 max 之间的成员数量。

    min 和 max 的语义与 ZRANGEBYSCORE 命令一致。

    注意:此命令的复杂度仅为 O(log(N)) 是因为他查询的 member 是有序的。因此,查询无需遍历整个排序集。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zcount('zset', '-inf', '+inf')
    // 3
    await client.zcount('zset', '(1', '3')
    // 2
    

    Parameters

    Returns Promise<number>

zdiff

  • zdiff(keys: [string | Buffer, ...(string | Buffer)[]]): Promise<(string | Buffer)[]>
  • zdiff(keys: [string | Buffer, ...(string | Buffer)[]], withscores: true): Promise<MemberScoreArray>
    • Redis官方文档https://redis.io/commands/zdiff
    • 起始版本:6.2.0
    • 时间复杂度:最坏情况复杂度为 O(L+(N-K)log(N)),L 是全部排序集中的成员数量,N 是第一个排序集的成员数量,K 是结果集的大小。

    这个命令类似 ZDIFFSTORE,区别是 ZDIFF 不会存储结果,而是将结果返回到客户端。

    例子:

    await client.zadd('zset1', { one: 1, two: 2, three: 3 })
    // 3
    await client.zadd('zset2', { one: 1, two: 2 })
    // 2
    await client.zdiff(['zset1', 'zset2'])
    // ["three"]
    await client.zdiff(['zset1', 'zset2'], true)
    // ["three", "3"]
    

    Parameters

    • keys: [string | Buffer, ...(string | Buffer)[]]

    Returns Promise<(string | Buffer)[]>

    • 数组形式返回一系列 member/score 对。
    • Redis官方文档https://redis.io/commands/zdiff
    • 起始版本:6.2.0
    • 时间复杂度:最坏情况复杂度为 O(L+(N-K)log(N)),L 是全部排序集中的成员数量,N 是第一个排序集的成员数量,K 是结果集的大小。

    这个命令类似 ZDIFFSTORE,区别是 ZDIFF 不会存储结果,而是将结果返回到客户端。

    例子:

    await client.zadd('zset1', { one: 1, two: 2, three: 3 })
    // 3
    await client.zadd('zset2', { one: 1, two: 2 })
    // 2
    await client.zdiff(['zset1', 'zset2'])
    // ["three"]
    await client.zdiff(['zset1', 'zset2'], true)
    // ["three", "3"]
    

    Parameters

    • keys: [string | Buffer, ...(string | Buffer)[]]
    • withscores: true

      以 member/score 对形式返回结果。

    Returns Promise<MemberScoreArray>

    • 数组形式返回一系列 member/score 对。

zdiffstore

  • zdiffstore(destination: string | Buffer, keys: [string | Buffer, ...(string | Buffer)[]]): Promise<number>
    • Redis官方文档https://redis.io/commands/zdiffstore
    • 起始版本:6.2.0
    • 时间复杂度:最坏情况复杂度为 O(L+(N-K)log(N)),L 是全部排序集中的成员数量,N 是第一个排序集的成员数量,K 是结果集的大小。

    计算第一个排序集和随后的其他排序集的差集,并将结果存入 destination。
    不存在的 key 被认为是个空集。
    如果 destination 已经存在则会被重写。

    例子:

    await client.zadd('zset1', { one: 1, two: 2, three: 3 })
    // 3
    await client.zadd('zset2', { one: 1, two: 2 })
    // 2
    await client.zdiffstore('out', ['zset1', 'zset2'])
    // 1
    await client.zrange('out', { by: 'BYSCORE', min: '-inf', max: '+inf' }, true)
    // ["three", "3"]
    

    Parameters

    • destination: string | Buffer

      用来存储结果的目标 key。

    • keys: [string | Buffer, ...(string | Buffer)[]]

    Returns Promise<number>

    • 返回存入 destination 的结果集的成员数量。

zincrby

  • zincrby(key: string | Buffer, increment: number | `${number}`, member: string | Buffer): Promise<`${number}`>
  • 将指定 member 的 score 进行自增操作。
    如果 member 不存在,就将自增值直接存到 member(就像它之前的值是 0.0)。
    如果 key 不存在,则创建一个只含有 member 的排序集。

    如果 key 存在但是值不是排序集则会返回错误。

    score 需要是字符串形式的数字,可以接受双精度浮点数。可以通过指定一个负数的 score 来进行自减操作。

    例子:

    await client.zadd('zset', { one: 1, two: 2 })
    // 2
    await client.zincrby('zset', '2', 'one')
    // "3"
    await client.zrange('zset', { min: 0, max: -1 }, true)
    // ["two", "2", "three", "3"]
    

    Parameters

    • key: string | Buffer
    • increment: number | `${number}`
    • member: string | Buffer

    Returns Promise<`${number}`>

    • 返回计算后的 score,字符串形式的双精度浮点数。

zinter

    • Redis官方文档https://redis.io/commands/zinter
    • 起始版本:6.2.0
    • 时间复杂度:最坏情况复杂度为 O(NK)+O(Mlog(M)) N 是最小排序集,K 是排序集数量,M 是结果集大小。

    这个命令类似 ZINTERSTORE 命令,区别是 ZINTER 不会存储结果,而是将结果返回到客户端。

    具体参数选项的语义请参考 ZINTERSTORE 命令。

    例子:

    await client.zadd('zset1', { one: 1, two: 2 })
    // 2
    await client.zadd('zset2', { one: 1, two: 2, three: 3 })
    // 3
    await client.zinter(['zset1', 'zset2'])
    // ["one", "two"]
    await client.zinter(['zset1', 'zset2'], true)
    // ["one", "2", "two", "4"]
    

    Type parameters

    • T: [string | Buffer, ...(string | Buffer)[]]

    Parameters

    Returns Promise<(string | Buffer)[]>

    • 返回交集计算的结果集。
    • Redis官方文档https://redis.io/commands/zinter
    • 起始版本:6.2.0
    • 时间复杂度:最坏情况复杂度为 O(NK)+O(Mlog(M)) N 是最小排序集,K 是排序集数量,M 是结果集大小。

    这个命令类似 ZINTERSTORE 命令,区别是 ZINTER 不会存储结果,而是将结果返回到客户端。

    具体参数选项的语义请参考 ZINTERSTORE 命令。

    例子:

    await client.zadd('zset1', { one: 1, two: 2 })
    // 2
    await client.zadd('zset2', { one: 1, two: 2, three: 3 })
    // 3
    await client.zinter(['zset1', 'zset2'])
    // ["one", "two"]
    await client.zinter(['zset1', 'zset2'], true)
    // ["one", "2", "two", "4"]
    

    Type parameters

    • T: [string | Buffer, ...(string | Buffer)[]]

    Parameters

    • keys: T
    • withscores: true

      以 member/score 对形式返回结果。

    • Optional options: ZinterOptions<T>

    Returns Promise<MemberScoreArray>

    • 返回交集计算的结果集。

zinterstore

  • zinterstore<T>(destination: string | Buffer, keys: [string | Buffer, ...(string | Buffer)[]], options?: ZinterOptions<T>): Promise<number>
    • Redis官方文档https://redis.io/commands/zinterstore
    • 起始版本:2.0.0
    • 时间复杂度:最坏情况复杂度为 O(NK)+O(Mlog(M)) N 是最小排序集,K 是排序集数量,M 是结果集大小。

    计算给定一系列的排序集的交集,并将结果存储到 destination 中。如果 destination 已经存在则会被重写。

    默认结果集中的 score 是该成员在所有集合中对应的 score 的和。

    aggregateweights 参数的说明见 ZUNIONSTORE 命令。

    例子:

    await client.zadd('zset1', { one: 1, two: 2 })
    // 2
    await client.zadd('zset2', { one: 1, two: 2, three: 3 })
    // 3
    await client.zinterstore('out', ['zset1', 'zset2'], { weights: [2, 3] })
    // 2
    await client.zrange('out', { min: 0, max: -1 }, true)
    // ["one", "5", "two", "10"]
    

    Type parameters

    • T: [string | Buffer, ...(string | Buffer)[]]

    Parameters

    • destination: string | Buffer
    • keys: [string | Buffer, ...(string | Buffer)[]]
    • Optional options: ZinterOptions<T>

    Returns Promise<number>

    • 返回结果集中的元素数量。

zlexcount

  • 当排序集中的全部元素使用相同的分数存储时,成员按照字典序排列,此时此命令可以用来返回字典序在 min 和 max 之间的成员。

    minmax 参数的详细语义参考 ZRANGEBYLEX 命令。

    例子:

    await client.zadd('zset', { a: 0, b: 0, c: 0, d: 0, e: 0 })
    // 5
    await client.zadd('zset', { f: 0, g: 0 })
    // 2
    await client.zlexcount('zset', '-', '+')
    // 7
    await client.zlexcount('zset', '[b', '[f')
    // 5
    

    Parameters

    Returns Promise<number>

    • 返回符合选择范围的成员数量。

zmscore

  • zmscore(key: string | Buffer, members: [string | Buffer, ...(string | Buffer)[]]): Promise<(null | `${number}`)[]>
  • 以数组形式返回指定的一系列 member 对应的 score。
    对于每个不存在的 member 返回 null。

    例子:

    await client.zadd('myzset', { one: 1 })
    // 1
    await client.zadd('myzset', { two: 2 })
    // 1
    await client.zmscore('myzset', ['one', 'two', 'nofield'])
    // ["1", "2", null]
    

    Parameters

    • key: string | Buffer
    • members: [string | Buffer, ...(string | Buffer)[]]

    Returns Promise<(null | `${number}`)[]>

zpopmax

    • Redis官方文档https://redis.io/commands/zpopmax
    • 起始版本:5.0.0
    • 时间复杂度:O(log(N) * M) N 是排序集的元素个数,M 是弹出的元素个数。

    移除并返回排序集中 score 排名前 count 个 member/score。

    • 如果不指定 count,则默认 count 为 1。
    • 如果指定的 count 比排序集的 member 个数还多,会弹出全部元素,而不是返回错误。
    • 返回的 member 按照分数从高到低排序。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3, four: 4 })
    // 4
    await client.zpopmax('zset', 2)
    // ["four", "4", "three", "3"]
    await client.zpopmax('zset')
    // ["two", "2"]
    

    Parameters

    • key: string | Buffer
    • Optional count: number

    Returns Promise<MemberScoreArray>

zpopmin

    • Redis官方文档https://redis.io/commands/zpopmin
    • 起始版本:5.0.0
    • 时间复杂度:O(log(N) * M) N 是排序集的元素个数,M 是弹出的元素个数。

    移除并返回排序集中 score 排名后 count 个 member/score。

    • 如果不指定 count,则默认 count 为 1。
    • 如果指定的 count 比排序集的 member 个数还多,会弹出全部元素,而不是返回错误。
    • 返回的 member 按照分数从低到高排序。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3, four: 4 })
    // 4
    await client.zpopmin('zset', 2)
    // ["one", "1", "two", "2"]
    await client.zpopmin('zset')
    // ["three", "3"]
    

    Parameters

    • key: string | Buffer
    • Optional count: number

    Returns Promise<MemberScoreArray>

zrange

    • Redis官方文档https://redis.io/commands/zrange
    • 起始版本:1.2.0
    • 时间复杂度:O(log(N)+M) N 是排序集中的成员个数,M 是结果元素成员。

    返回指定范围的成员,通过指定 range 参数中的 by 选项,可以让命令实施不同的行为。默认按照索引排序选取。

    6.2.0 版本开始,ZRANGE 可以替代 ZREVRANGEZRANGEBYSCOREZREVRANGEBYSCOREZRANGEBYLEXZREVRANGEBYLEX 五个命令。

    公共行为和选项

    成员的排列顺序为从低到高。分数相同的成员按照字典序排列。

    • reverse 参数将排序方式改为从高到低,包括字典序。
    • limit 参数可以限定返回值得范围(类似 SQL 中的 LIMIT offset, count)。负数的 count 表示获取跳过 offset 个元素后的全部元素。
    • withscores 参数表示让命令返回 member/score 对,而不是只返回 member 本身。

    索引范围选择

    ZRANGE 默认按照索引排序进行范围选取。min 和 max 参数是从 0 开始的索引计数,0 表示第一个元素,1 表示第二个元素,以此类推。
    这些参数指定了一个闭区间,比如:{min: 0, max: 1} 表示的范围就是排序集的第一个和第二个元素。

    索引可以是负数,表示到排序集末尾的距离,-1 表示最后一个元素,-2 表示倒数第二个元素,以此类推。

    超出实际范围的索引会导致返回错误。

    如果 min 比 max 大或者比 end 对应的索引大,会返回一个空列表。
    如果 max 比 end 对应的索引大,Redis 会认为这个 max 指定了最后一个元素。

    分数范围选择

    当 range 参数中设置了 BYSCORE,命令行为会和 ZRANGEBYSCORE 命令一致,返回分数介于 min 和 max 之间的成员。

    minmax 可以使用值,'-inf''+inf',分别表示负无穷大和正无穷大。这意味着你不需要知道实际的最大分数或最小分数,也能选取全部的成员。

    通过 min 和 max 指定的区间范围默认是闭区间,也就是包含 min 和 max 本身。可以通过在分数前缀 ( 表示排除 min 或者 max。

    字典序范围选择

    当 range 参数中设置了 BYLEX,命令行为会和 ZRANGEBYLEX 命令一致,按照字典序返回介于 min 和 max 之间的元素。

    注意:字典序范围选取依赖 排序集中的成员分数全部一致,在分数不一致的情况下,选取行为是未定义的。

    在字典序模式下,min 和 max 必须以 ((不包含本身) 或 [(包含本身)开头。

    min 和 max 可以使用特殊值 -+ 分别表示无穷小的字符串和无穷大的字符串。

    字典序:member 名称(字符串)被认为是一个 byte array,通过逐位比较大小确定排序。这和字符串的字符集有关。

    例子:

    await client.zadd('myzset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrange('myzset', { min: 0, max: -1 })
    // ["one", "two", "three"]
    await client.zrange('myzset', { min: 2, max: 3 })
    // ["three"]
    await client.zrange('myzset', { min: -2, max: -1 })
    // ["two", "three"]
    await client.zrange('myzset', { min: 0, max: 1 }, true)
    // ["one", "1", "two", "2"]
    await client.zrange('myzset', { by: 'BYSCORE', min: '(1', max: '+inf' }, { limit: [1, 1] })
    // ["three"]
    

    Parameters

    • key: string | Buffer
    • range: { max: number; min: number }
      • max: number
      • min: number
    • Optional options: Pick<ZrangeOptions, "reverse">

    Returns Promise<(string | Buffer)[]>

    • Redis官方文档https://redis.io/commands/zrange
    • 起始版本:1.2.0
    • 时间复杂度:O(log(N)+M) N 是排序集中的成员个数,M 是结果元素成员。

    返回指定范围的成员,通过指定 range 参数中的 by 选项,可以让命令实施不同的行为。默认按照索引排序选取。

    6.2.0 版本开始,ZRANGE 可以替代 ZREVRANGEZRANGEBYSCOREZREVRANGEBYSCOREZRANGEBYLEXZREVRANGEBYLEX 五个命令。

    公共行为和选项

    成员的排列顺序为从低到高。分数相同的成员按照字典序排列。

    • reverse 参数将排序方式改为从高到低,包括字典序。
    • limit 参数可以限定返回值得范围(类似 SQL 中的 LIMIT offset, count)。负数的 count 表示获取跳过 offset 个元素后的全部元素。
    • withscores 参数表示让命令返回 member/score 对,而不是只返回 member 本身。

    索引范围选择

    ZRANGE 默认按照索引排序进行范围选取。min 和 max 参数是从 0 开始的索引计数,0 表示第一个元素,1 表示第二个元素,以此类推。
    这些参数指定了一个闭区间,比如:{min: 0, max: 1} 表示的范围就是排序集的第一个和第二个元素。

    索引可以是负数,表示到排序集末尾的距离,-1 表示最后一个元素,-2 表示倒数第二个元素,以此类推。

    超出实际范围的索引会导致返回错误。

    如果 min 比 max 大或者比 end 对应的索引大,会返回一个空列表。
    如果 max 比 end 对应的索引大,Redis 会认为这个 max 指定了最后一个元素。

    分数范围选择

    当 range 参数中设置了 BYSCORE,命令行为会和 ZRANGEBYSCORE 命令一致,返回分数介于 min 和 max 之间的成员。

    minmax 可以使用值,'-inf''+inf',分别表示负无穷大和正无穷大。这意味着你不需要知道实际的最大分数或最小分数,也能选取全部的成员。

    通过 min 和 max 指定的区间范围默认是闭区间,也就是包含 min 和 max 本身。可以通过在分数前缀 ( 表示排除 min 或者 max。

    字典序范围选择

    当 range 参数中设置了 BYLEX,命令行为会和 ZRANGEBYLEX 命令一致,按照字典序返回介于 min 和 max 之间的元素。

    注意:字典序范围选取依赖 排序集中的成员分数全部一致,在分数不一致的情况下,选取行为是未定义的。

    在字典序模式下,min 和 max 必须以 ((不包含本身) 或 [(包含本身)开头。

    min 和 max 可以使用特殊值 -+ 分别表示无穷小的字符串和无穷大的字符串。

    字典序:member 名称(字符串)被认为是一个 byte array,通过逐位比较大小确定排序。这和字符串的字符集有关。

    例子:

    await client.zadd('myzset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrange('myzset', { min: 0, max: -1 })
    // ["one", "two", "three"]
    await client.zrange('myzset', { min: 2, max: 3 })
    // ["three"]
    await client.zrange('myzset', { min: -2, max: -1 })
    // ["two", "three"]
    await client.zrange('myzset', { min: 0, max: 1 }, true)
    // ["one", "1", "two", "2"]
    await client.zrange('myzset', { by: 'BYSCORE', min: '(1', max: '+inf' }, { limit: [1, 1] })
    // ["three"]
    

    Parameters

    • key: string | Buffer
    • range: { max: number; min: number }
      • max: number
      • min: number
    • withscores: true

      以 member/score 对形式返回结果。

    • Optional options: Pick<ZrangeOptions, "reverse">

    Returns Promise<MemberScoreArray>

    • Redis官方文档https://redis.io/commands/zrange
    • 起始版本:1.2.0
    • 时间复杂度:O(log(N)+M) N 是排序集中的成员个数,M 是结果元素成员。

    返回指定范围的成员,通过指定 range 参数中的 by 选项,可以让命令实施不同的行为。默认按照索引排序选取。

    6.2.0 版本开始,ZRANGE 可以替代 ZREVRANGEZRANGEBYSCOREZREVRANGEBYSCOREZRANGEBYLEXZREVRANGEBYLEX 五个命令。

    公共行为和选项

    成员的排列顺序为从低到高。分数相同的成员按照字典序排列。

    • reverse 参数将排序方式改为从高到低,包括字典序。
    • limit 参数可以限定返回值得范围(类似 SQL 中的 LIMIT offset, count)。负数的 count 表示获取跳过 offset 个元素后的全部元素。
    • withscores 参数表示让命令返回 member/score 对,而不是只返回 member 本身。

    索引范围选择

    ZRANGE 默认按照索引排序进行范围选取。min 和 max 参数是从 0 开始的索引计数,0 表示第一个元素,1 表示第二个元素,以此类推。
    这些参数指定了一个闭区间,比如:{min: 0, max: 1} 表示的范围就是排序集的第一个和第二个元素。

    索引可以是负数,表示到排序集末尾的距离,-1 表示最后一个元素,-2 表示倒数第二个元素,以此类推。

    超出实际范围的索引会导致返回错误。

    如果 min 比 max 大或者比 end 对应的索引大,会返回一个空列表。
    如果 max 比 end 对应的索引大,Redis 会认为这个 max 指定了最后一个元素。

    分数范围选择

    当 range 参数中设置了 BYSCORE,命令行为会和 ZRANGEBYSCORE 命令一致,返回分数介于 min 和 max 之间的成员。

    minmax 可以使用值,'-inf''+inf',分别表示负无穷大和正无穷大。这意味着你不需要知道实际的最大分数或最小分数,也能选取全部的成员。

    通过 min 和 max 指定的区间范围默认是闭区间,也就是包含 min 和 max 本身。可以通过在分数前缀 ( 表示排除 min 或者 max。

    字典序范围选择

    当 range 参数中设置了 BYLEX,命令行为会和 ZRANGEBYLEX 命令一致,按照字典序返回介于 min 和 max 之间的元素。

    注意:字典序范围选取依赖 排序集中的成员分数全部一致,在分数不一致的情况下,选取行为是未定义的。

    在字典序模式下,min 和 max 必须以 ((不包含本身) 或 [(包含本身)开头。

    min 和 max 可以使用特殊值 -+ 分别表示无穷小的字符串和无穷大的字符串。

    字典序:member 名称(字符串)被认为是一个 byte array,通过逐位比较大小确定排序。这和字符串的字符集有关。

    例子:

    await client.zadd('myzset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrange('myzset', { min: 0, max: -1 })
    // ["one", "two", "three"]
    await client.zrange('myzset', { min: 2, max: 3 })
    // ["three"]
    await client.zrange('myzset', { min: -2, max: -1 })
    // ["two", "three"]
    await client.zrange('myzset', { min: 0, max: 1 }, true)
    // ["one", "1", "two", "2"]
    await client.zrange('myzset', { by: 'BYSCORE', min: '(1', max: '+inf' }, { limit: [1, 1] })
    // ["three"]
    

    Parameters

    Returns Promise<(string | Buffer)[]>

    • Redis官方文档https://redis.io/commands/zrange
    • 起始版本:1.2.0
    • 时间复杂度:O(log(N)+M) N 是排序集中的成员个数,M 是结果元素成员。

    返回指定范围的成员,通过指定 range 参数中的 by 选项,可以让命令实施不同的行为。默认按照索引排序选取。

    6.2.0 版本开始,ZRANGE 可以替代 ZREVRANGEZRANGEBYSCOREZREVRANGEBYSCOREZRANGEBYLEXZREVRANGEBYLEX 五个命令。

    公共行为和选项

    成员的排列顺序为从低到高。分数相同的成员按照字典序排列。

    • reverse 参数将排序方式改为从高到低,包括字典序。
    • limit 参数可以限定返回值得范围(类似 SQL 中的 LIMIT offset, count)。负数的 count 表示获取跳过 offset 个元素后的全部元素。
    • withscores 参数表示让命令返回 member/score 对,而不是只返回 member 本身。

    索引范围选择

    ZRANGE 默认按照索引排序进行范围选取。min 和 max 参数是从 0 开始的索引计数,0 表示第一个元素,1 表示第二个元素,以此类推。
    这些参数指定了一个闭区间,比如:{min: 0, max: 1} 表示的范围就是排序集的第一个和第二个元素。

    索引可以是负数,表示到排序集末尾的距离,-1 表示最后一个元素,-2 表示倒数第二个元素,以此类推。

    超出实际范围的索引会导致返回错误。

    如果 min 比 max 大或者比 end 对应的索引大,会返回一个空列表。
    如果 max 比 end 对应的索引大,Redis 会认为这个 max 指定了最后一个元素。

    分数范围选择

    当 range 参数中设置了 BYSCORE,命令行为会和 ZRANGEBYSCORE 命令一致,返回分数介于 min 和 max 之间的成员。

    minmax 可以使用值,'-inf''+inf',分别表示负无穷大和正无穷大。这意味着你不需要知道实际的最大分数或最小分数,也能选取全部的成员。

    通过 min 和 max 指定的区间范围默认是闭区间,也就是包含 min 和 max 本身。可以通过在分数前缀 ( 表示排除 min 或者 max。

    字典序范围选择

    当 range 参数中设置了 BYLEX,命令行为会和 ZRANGEBYLEX 命令一致,按照字典序返回介于 min 和 max 之间的元素。

    注意:字典序范围选取依赖 排序集中的成员分数全部一致,在分数不一致的情况下,选取行为是未定义的。

    在字典序模式下,min 和 max 必须以 ((不包含本身) 或 [(包含本身)开头。

    min 和 max 可以使用特殊值 -+ 分别表示无穷小的字符串和无穷大的字符串。

    字典序:member 名称(字符串)被认为是一个 byte array,通过逐位比较大小确定排序。这和字符串的字符集有关。

    例子:

    await client.zadd('myzset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrange('myzset', { min: 0, max: -1 })
    // ["one", "two", "three"]
    await client.zrange('myzset', { min: 2, max: 3 })
    // ["three"]
    await client.zrange('myzset', { min: -2, max: -1 })
    // ["two", "three"]
    await client.zrange('myzset', { min: 0, max: 1 }, true)
    // ["one", "1", "two", "2"]
    await client.zrange('myzset', { by: 'BYSCORE', min: '(1', max: '+inf' }, { limit: [1, 1] })
    // ["three"]
    

    Parameters

    Returns Promise<(string | Buffer)[]>

    • Redis官方文档https://redis.io/commands/zrange
    • 起始版本:1.2.0
    • 时间复杂度:O(log(N)+M) N 是排序集中的成员个数,M 是结果元素成员。

    返回指定范围的成员,通过指定 range 参数中的 by 选项,可以让命令实施不同的行为。默认按照索引排序选取。

    6.2.0 版本开始,ZRANGE 可以替代 ZREVRANGEZRANGEBYSCOREZREVRANGEBYSCOREZRANGEBYLEXZREVRANGEBYLEX 五个命令。

    公共行为和选项

    成员的排列顺序为从低到高。分数相同的成员按照字典序排列。

    • reverse 参数将排序方式改为从高到低,包括字典序。
    • limit 参数可以限定返回值得范围(类似 SQL 中的 LIMIT offset, count)。负数的 count 表示获取跳过 offset 个元素后的全部元素。
    • withscores 参数表示让命令返回 member/score 对,而不是只返回 member 本身。

    索引范围选择

    ZRANGE 默认按照索引排序进行范围选取。min 和 max 参数是从 0 开始的索引计数,0 表示第一个元素,1 表示第二个元素,以此类推。
    这些参数指定了一个闭区间,比如:{min: 0, max: 1} 表示的范围就是排序集的第一个和第二个元素。

    索引可以是负数,表示到排序集末尾的距离,-1 表示最后一个元素,-2 表示倒数第二个元素,以此类推。

    超出实际范围的索引会导致返回错误。

    如果 min 比 max 大或者比 end 对应的索引大,会返回一个空列表。
    如果 max 比 end 对应的索引大,Redis 会认为这个 max 指定了最后一个元素。

    分数范围选择

    当 range 参数中设置了 BYSCORE,命令行为会和 ZRANGEBYSCORE 命令一致,返回分数介于 min 和 max 之间的成员。

    minmax 可以使用值,'-inf''+inf',分别表示负无穷大和正无穷大。这意味着你不需要知道实际的最大分数或最小分数,也能选取全部的成员。

    通过 min 和 max 指定的区间范围默认是闭区间,也就是包含 min 和 max 本身。可以通过在分数前缀 ( 表示排除 min 或者 max。

    字典序范围选择

    当 range 参数中设置了 BYLEX,命令行为会和 ZRANGEBYLEX 命令一致,按照字典序返回介于 min 和 max 之间的元素。

    注意:字典序范围选取依赖 排序集中的成员分数全部一致,在分数不一致的情况下,选取行为是未定义的。

    在字典序模式下,min 和 max 必须以 ((不包含本身) 或 [(包含本身)开头。

    min 和 max 可以使用特殊值 -+ 分别表示无穷小的字符串和无穷大的字符串。

    字典序:member 名称(字符串)被认为是一个 byte array,通过逐位比较大小确定排序。这和字符串的字符集有关。

    例子:

    await client.zadd('myzset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrange('myzset', { min: 0, max: -1 })
    // ["one", "two", "three"]
    await client.zrange('myzset', { min: 2, max: 3 })
    // ["three"]
    await client.zrange('myzset', { min: -2, max: -1 })
    // ["two", "three"]
    await client.zrange('myzset', { min: 0, max: 1 }, true)
    // ["one", "1", "two", "2"]
    await client.zrange('myzset', { by: 'BYSCORE', min: '(1', max: '+inf' }, { limit: [1, 1] })
    // ["three"]
    

    Parameters

    Returns Promise<MemberScoreArray>

zrangebylex

    • Redis官方文档https://redis.io/commands/zrangebylex
    • 起始版本:2.8.9
    • 时间复杂度:O(log(N)+M) N 是排序集中的成员数量,M 是需要返回的成员数量。
      如果 M 始终是个常量(比如使用 limit 限制始终返回前 10 个元素),此时可以认为复杂度为 O(log(N))。

    当排序集中的全部成员含有相同的 score 时,成员按照字典序排列,ZRANGEBYLEX 可以在这种情况下返回字典序介于 min 和 max 之间的所有成员。

    成员按照从低到高的顺序排列,比较方式是 c 函数 memcmp(),也就是逐个字节比较字符串。如果公共部分相同,更长的字符串更大。

    在 Redis 6.2.0 版本,这个命令可能被废弃。请在新代码中使用带 BYLEX 参数的 ZRANGE 命令。

    可选参数 limit 可以用来限制返回成员数量(类似 SQL 中的 SELECT LIMIT offset, count)。负数的 count 表示返回 offset 后的全部元素。
    需要注意的是,如果 offset 很大,排序集在找到需要返回的元素前要先遍历 offset 个元素。这可能会增加 O(N) 的复杂度。

    如何指定区间

    合法的 min 和 max 值需要以 [ 或者 ( 开头,分别表示端值被包含和不被包含。特殊值 +- 分表表示无穷大和无穷小的字符串。
    所以当全部成员有相同的分数时 await client.zrangebylex('zset', '-', '+') 表示选择全部成员。

    字符串比较细节

    字符串作为字节数组进行比较,这在使用纯 ASCII 编码时没有问题,因为 ASCII 编码的字节顺序就是按照字典顺序来的。但是在使用其他字符编码是情况则不一定如此,比如 UTF-8 编码。

    另外,用户可以自己做一个转码,保证最前面部分的字符串编码是按照期望进行排列的。

    比如,你希望进行一个大小写不敏感的字符串排序,但是又希望保留原始字符串,那你可以如下设置一个排序集:

    zset { 'foo:Foo': 0, 'bar:BAR': 0, 'zap:zap': 0 }

    将全部字符转为小写,并通过分号和原字符串拼接起来。由于分号的字节比所有字母都要大,所以可以通过这种方式强制按照分号前的部分进行排序。而应用可以根据查询结果进行分割限制后面一部分的实际内容。

    利用二进制进行比较的特性,可以让排序集成为通用索引。
    例如,元素的第一部分可以是 64 位大端数字:由于大端数字在初始位置具有最高有效字节,因此二进制比较的结果和直接比较数字是一致的。
    可以使用它来对 64 位值执行范围查询。

    例子:

    await client.zadd('zset', { a: 0, b: 0, c: 0, d: 0, e: 0, f: 0, g: 0 })
    // 7
    await client.zrangebylex('zset', '-', '[c')
    // ["a", "b", "c"]
    await client.zrangebylex('zset', '-', '(c')
    // ["a", "b"]
    await client.zrangebylex('zset', '[aaa', '(g')
    // ["b", "c", "d", "e", "f"]
    

    Parameters

    • key: string | Buffer
    • min: ZsetRangeMemberMin

      选取范围的最小值。

    • max: ZsetRangeMemberMin

      选取范围的最大值。

    • Optional limit: [number, number]

      限制返回成员数量,格式为 offset, count

    Returns Promise<MemberArray>

zrangebyscore

    • Redis官方文档https://redis.io/commands/zrangebyscore
    • 起始版本:1.0.5
    • 时间复杂度:O(log(N)+M) N 是排序集中的成员数量,M 是需要返回的成员数量。
      如果 M 始终是个常量(比如使用 limit 限制始终返回前 10 个元素),此时可以认为复杂度为 O(log(N))。

    返回排序集中 score 在 min 和 max 之间的一系列 member。当设置了 withscores 参数时,返回一系列 member/score 对。
    返回元素默认按照分数从小到大排列。

    具有相同分数的成员按照字典序排列(这来自于 Redis 排序集的一个默认行为,不涉及进一步计算)。

    在 Redis 6.2.0 版本,这个命令可能被废弃。请在新代码中使用带 BYSCORE 参数的 ZRANGE 命令。

    可选参数 limit 可以用来限制返回成员数量(类似 SQL 中的 SELECT LIMIT offset, count)。负数的 count 表示返回 offset 后的全部元素。
    需要注意的是,如果 offset 很大,排序集在找到需要返回的元素前要先遍历 offset 个元素。这可能会增加 O(N) 的复杂度。

    可选参数 withscores 表示让命令返回 member/score 对,而不是只返回 member 本身。这个选项在 2.0 版本开始可用。

    开区间和无穷大

    min 和 max 可以使用值 '-inf'+inf 分别表示排序集中的最小值和最大值。
    默认指定的 min 和 max 是被包含在选择范围内的(闭区间)。
    通过添加前缀 '(' 可以表示排除 min 或者 max 本身(开区间)。
    如:(1 5 表示 1 < score <= 5(5 (10 表示 5 < score < 10

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrangebyscore('zset', '-inf', '+inf')
    // ["one", "two", "three"]
    await client.zrangebyscore('zset', '1', '2')
    // ["one", "two"]
    await client.zrangebyscore('zset', '(1', '2')
    // ["two"]
    await client.zrangebyscore('zset', '(1', '(2')
    // []
    

    Parameters

    Returns Promise<(string | Buffer)[]>

    • Redis官方文档https://redis.io/commands/zrangebyscore
    • 起始版本:1.0.5
    • 时间复杂度:O(log(N)+M) N 是排序集中的成员数量,M 是需要返回的成员数量。
      如果 M 始终是个常量(比如使用 limit 限制始终返回前 10 个元素),此时可以认为复杂度为 O(log(N))。

    返回排序集中 score 在 min 和 max 之间的一系列 member。当设置了 withscores 参数时,返回一系列 member/score 对。
    返回元素默认按照分数从小到大排列。

    具有相同分数的成员按照字典序排列(这来自于 Redis 排序集的一个默认行为,不涉及进一步计算)。

    在 Redis 6.2.0 版本,这个命令可能被废弃。请在新代码中使用带 BYSCORE 参数的 ZRANGE 命令。

    可选参数 limit 可以用来限制返回成员数量(类似 SQL 中的 SELECT LIMIT offset, count)。负数的 count 表示返回 offset 后的全部元素。
    需要注意的是,如果 offset 很大,排序集在找到需要返回的元素前要先遍历 offset 个元素。这可能会增加 O(N) 的复杂度。

    可选参数 withscores 表示让命令返回 member/score 对,而不是只返回 member 本身。这个选项在 2.0 版本开始可用。

    开区间和无穷大

    min 和 max 可以使用值 '-inf'+inf 分别表示排序集中的最小值和最大值。
    默认指定的 min 和 max 是被包含在选择范围内的(闭区间)。
    通过添加前缀 '(' 可以表示排除 min 或者 max 本身(开区间)。
    如:(1 5 表示 1 < score <= 5(5 (10 表示 5 < score < 10

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrangebyscore('zset', '-inf', '+inf')
    // ["one", "two", "three"]
    await client.zrangebyscore('zset', '1', '2')
    // ["one", "two"]
    await client.zrangebyscore('zset', '(1', '2')
    // ["two"]
    await client.zrangebyscore('zset', '(1', '(2')
    // []
    

    Parameters

    • key: string | Buffer
    • min: ZsetRangeScoreMin

      选取范围的最小值。

    • max: ZsetRangeScoreMin

      选取范围的最大值。

    • withscores: true

      以 member/score 对形式返回结果,2.0.0 版本开始可用。

    Returns Promise<MemberScoreArray>

    • Redis官方文档https://redis.io/commands/zrangebyscore
    • 起始版本:1.0.5
    • 时间复杂度:O(log(N)+M) N 是排序集中的成员数量,M 是需要返回的成员数量。
      如果 M 始终是个常量(比如使用 limit 限制始终返回前 10 个元素),此时可以认为复杂度为 O(log(N))。

    返回排序集中 score 在 min 和 max 之间的一系列 member。当设置了 withscores 参数时,返回一系列 member/score 对。
    返回元素默认按照分数从小到大排列。

    具有相同分数的成员按照字典序排列(这来自于 Redis 排序集的一个默认行为,不涉及进一步计算)。

    在 Redis 6.2.0 版本,这个命令可能被废弃。请在新代码中使用带 BYSCORE 参数的 ZRANGE 命令。

    可选参数 limit 可以用来限制返回成员数量(类似 SQL 中的 SELECT LIMIT offset, count)。负数的 count 表示返回 offset 后的全部元素。
    需要注意的是,如果 offset 很大,排序集在找到需要返回的元素前要先遍历 offset 个元素。这可能会增加 O(N) 的复杂度。

    可选参数 withscores 表示让命令返回 member/score 对,而不是只返回 member 本身。这个选项在 2.0 版本开始可用。

    开区间和无穷大

    min 和 max 可以使用值 '-inf'+inf 分别表示排序集中的最小值和最大值。
    默认指定的 min 和 max 是被包含在选择范围内的(闭区间)。
    通过添加前缀 '(' 可以表示排除 min 或者 max 本身(开区间)。
    如:(1 5 表示 1 < score <= 5(5 (10 表示 5 < score < 10

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrangebyscore('zset', '-inf', '+inf')
    // ["one", "two", "three"]
    await client.zrangebyscore('zset', '1', '2')
    // ["one", "two"]
    await client.zrangebyscore('zset', '(1', '2')
    // ["two"]
    await client.zrangebyscore('zset', '(1', '(2')
    // []
    

    Parameters

    • key: string | Buffer
    • min: ZsetRangeScoreMin

      选取范围的最小值。

    • max: ZsetRangeScoreMin

      选取范围的最大值。

    • limit: [number, number]

      限制返回成员数量,格式为 offset, count

    Returns Promise<(string | Buffer)[]>

    • Redis官方文档https://redis.io/commands/zrangebyscore
    • 起始版本:1.0.5
    • 时间复杂度:O(log(N)+M) N 是排序集中的成员数量,M 是需要返回的成员数量。
      如果 M 始终是个常量(比如使用 limit 限制始终返回前 10 个元素),此时可以认为复杂度为 O(log(N))。

    返回排序集中 score 在 min 和 max 之间的一系列 member。当设置了 withscores 参数时,返回一系列 member/score 对。
    返回元素默认按照分数从小到大排列。

    具有相同分数的成员按照字典序排列(这来自于 Redis 排序集的一个默认行为,不涉及进一步计算)。

    在 Redis 6.2.0 版本,这个命令可能被废弃。请在新代码中使用带 BYSCORE 参数的 ZRANGE 命令。

    可选参数 limit 可以用来限制返回成员数量(类似 SQL 中的 SELECT LIMIT offset, count)。负数的 count 表示返回 offset 后的全部元素。
    需要注意的是,如果 offset 很大,排序集在找到需要返回的元素前要先遍历 offset 个元素。这可能会增加 O(N) 的复杂度。

    可选参数 withscores 表示让命令返回 member/score 对,而不是只返回 member 本身。这个选项在 2.0 版本开始可用。

    开区间和无穷大

    min 和 max 可以使用值 '-inf'+inf 分别表示排序集中的最小值和最大值。
    默认指定的 min 和 max 是被包含在选择范围内的(闭区间)。
    通过添加前缀 '(' 可以表示排除 min 或者 max 本身(开区间)。
    如:(1 5 表示 1 < score <= 5(5 (10 表示 5 < score < 10

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrangebyscore('zset', '-inf', '+inf')
    // ["one", "two", "three"]
    await client.zrangebyscore('zset', '1', '2')
    // ["one", "two"]
    await client.zrangebyscore('zset', '(1', '2')
    // ["two"]
    await client.zrangebyscore('zset', '(1', '(2')
    // []
    

    Parameters

    • key: string | Buffer
    • min: ZsetRangeScoreMin

      选取范围的最小值。

    • max: ZsetRangeScoreMin

      选取范围的最大值。

    • limit: [number, number]

      限制返回成员数量,格式为 offset, count

    • withscores: true

      以 member/score 对形式返回结果,2.0.0 版本开始可用。

    Returns Promise<MemberScoreArray>

zrangestore

  • 这个命令类似 ZRANGE 命令,区别是 ZRANGESTORE 会将结果存入 destination。

    返回结果集成员数量。

    例子:

    await client.zadd('srczset', { one: 1, two: 2, three: 3, four: 4 })
    // 4
    await client.zrangestore('dstzset', 'srczset', { min: 2, max: -1 })
    // 2
    await client.zrange('dstzset', { min: 0, max: -1 })
    // ["three", "four"]
    

    Parameters

    • dst: string | Buffer
    • src: string | Buffer
    • range: { max: number; min: number }
      • max: number
      • min: number
    • Optional options: Pick<ZrangeOptions, "reverse">

    Returns Promise<number>

    返回存入 destination 的结果集的成员数量。

  • 这个命令类似 ZRANGE 命令,区别是 ZRANGESTORE 会将结果存入 destination。

    返回结果集成员数量。

    例子:

    await client.zadd('srczset', { one: 1, two: 2, three: 3, four: 4 })
    // 4
    await client.zrangestore('dstzset', 'srczset', { min: 2, max: -1 })
    // 2
    await client.zrange('dstzset', { min: 0, max: -1 })
    // ["three", "four"]
    
    category

    Sorted Set

    Parameters

    Returns Promise<number>

    返回存入 destination 的结果集的成员数量。

  • 这个命令类似 ZRANGE 命令,区别是 ZRANGESTORE 会将结果存入 destination。

    返回结果集成员数量。

    例子:

    await client.zadd('srczset', { one: 1, two: 2, three: 3, four: 4 })
    // 4
    await client.zrangestore('dstzset', 'srczset', { min: 2, max: -1 })
    // 2
    await client.zrange('dstzset', { min: 0, max: -1 })
    // ["three", "four"]
    
    category

    Sorted Set

    Parameters

    Returns Promise<number>

    返回存入 destination 的结果集的成员数量。

zrank

  • zrank(key: string | Buffer, member: string | Buffer): Promise<null | number>
  • 返回 member 在排序集中的顺位,排序规则为按照 score 从低到高。顺位是从 0 开始计数的,也就是说 0 表示第一顺位。

    如果需要查询 score 从高到低的顺位可以使用 ZREVRANK 命令。

    返回值

    • 如果 member 存在,则返回整型表示的顺位。
    • 如果 member 不存在,返回 null。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrank('zset', 'three')
    // 2
    await client.zrank('zset', 'four')
    // null
    

    Parameters

    • key: string | Buffer
    • member: string | Buffer

    Returns Promise<null | number>

zrem

  • zrem(key: string | Buffer, members: [string | Buffer, ...(string | Buffer)[]]): Promise<number>
    • Redis官方文档https://redis.io/commands/zrem
    • 起始版本:1.2.0
    • 时间复杂度:O(M*log(N)) N 是排序集中的总元素数量,M 是需要移除的元素数量。

    从排序集移除指定成员。不存在的成员会被忽略。

    如果 key 存在但是对应的值不是排序集会返回错误。

    返回值

    返回从排序集中移除的成员数量,但是不包括不存在的成员。

    注意:2.4 版本开始可以指定多个 member,更早的版本中每次命令调用只能移除一个 member。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrem('zset', ['two'])
    // 1
    await client.zrange('zset', { min: 0, max: -1 }, true)
    // ["one", "1", "three", "3"]
    

    Parameters

    • key: string | Buffer
    • members: [string | Buffer, ...(string | Buffer)[]]

    Returns Promise<number>

zremrangebylex

  • 当排序集中的全部成员含有相同的 score 时,成员按照字典序排列,ZREMRANGEBYLEX 可以在这种情况下移除 min 和 max 之间的所有成员。

    此命令中的 min 和 max 的语义和 ZRANGEBYLEX 命令相同。

    例子:

    await client.zadd('zset', { aaaa: 0, b: 0, c: 0, d: 0, e: 0 })
    // 5
    await client.zadd('zset', { foo: 0, zap: 0, zip: 0, ALPHA: 0, alpha: 0 })
    // 5
    await client.zrange('zset', { min: 0, max: -1 })
    // ["ALPHA", "aaaa", "alpha", "b", "c", "d", "e", "foo", "zap", "zip"]
    await client.zremrangebylex('zset', '[alpha', '[omega')
    // 6
    await client.zrange('zset', { min: 0, max: -1 })
    // ["ALPHA", "aaaa", "alpha", "b", "c", "d", "e", "foo", "zap", "zip"]
    

    Parameters

    Returns Promise<number>

zremrangebyrank

  • zremrangebyrank(key: string | Buffer, start: number, stop: number): Promise<number>
  • 从排序集中移除顺位在 start 和 stop 中间的全部成员。

    start 和 stop 都是从 0 开始计数的从低到高的顺位。start 和 stop 可以是负数,表示从高到低的顺位。-1 表示倒数第一个元素,-2 表示倒数第二个元素,以此类推。

    返回值

    返回被移除的元素个数。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zremrangebyrank('zset', 0, 1)
    // 2
    await client.zrange('zset', { min: 0, max: -1 }, true)
    // ["three", "3"]
    

    Parameters

    • key: string | Buffer
    • start: number

      选取范围索引开始位置。

    • stop: number

      选取范围索引结束位置。

    Returns Promise<number>

zremrangebyscore

  • 从排序集中移除顺位在 min 和 max 中间,包括 min 和 max 的全部成员。

    注意:2.1.6 版本之后 min 和 max 可以被排除在选取范围外。具体语法见 ZRANGEBYSCORE 命令。

    返回值

    返回被移除的元素个数。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zremrangebyscore('zset', '-inf', '(2')
    // 1
    await client.zrange('zset', { min: 0, max: -1 }, true)
    // ["two", "2", "three", "3"]
    

    Parameters

    Returns Promise<number>

zrevrange

  • zrevrange(key: string | Buffer, start: number, stop: number): Promise<(string | Buffer)[]>
  • zrevrange(key: string | Buffer, start: number, stop: number, withscores: true): Promise<MemberScoreArray>
    • Redis官方文档https://redis.io/commands/zrevrange
    • 起始版本:1.2.0
    • 时间复杂度:O(log(N)+M) N 为排序集中的成员数量,M 为需要移除的成员数量。

    返回排序集中指定范围的成员。调用此命令时可以认为成员排序是按照分数从高到低的。
    相同分数的成员按照逆字典序排列。

    除了顺序是颠倒的以外,ZREVRANGE 和 ZRANGE 命令行为一样。

    注意:6.2.0 版本开始,ZRANGE 可以用来实现此命令的行为,可能在之后的版本中被废弃。

    返回值

    数组形式返回指定范围的一系列成员。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrevrange('zset', 0, -1)
    // ["three", "two", "one"]
    await client.zrevrange('zset', 2, 3)
    // ["one"]
    await client.zrevrange('zset', -2, -1)
    // ["two", "one"]
    

    Parameters

    • key: string | Buffer
    • start: number

      选取范围索引开始位置。

    • stop: number

      选取范围索引结束位置。

    Returns Promise<(string | Buffer)[]>

    • Redis官方文档https://redis.io/commands/zrevrange
    • 起始版本:1.2.0
    • 时间复杂度:O(log(N)+M) N 为排序集中的成员数量,M 为需要移除的成员数量。

    返回排序集中指定范围的成员。调用此命令时可以认为成员排序是按照分数从高到低的。
    相同分数的成员按照逆字典序排列。

    除了顺序是颠倒的以外,ZREVRANGE 和 ZRANGE 命令行为一样。

    注意:6.2.0 版本开始,ZRANGE 可以用来实现此命令的行为,可能在之后的版本中被废弃。

    返回值

    数组形式返回指定范围的一系列成员。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrevrange('zset', 0, -1)
    // ["three", "two", "one"]
    await client.zrevrange('zset', 2, 3)
    // ["one"]
    await client.zrevrange('zset', -2, -1)
    // ["two", "one"]
    

    Parameters

    • key: string | Buffer
    • start: number

      选取范围索引开始位置。

    • stop: number

      选取范围索引结束位置。

    • withscores: true

      以 member/score 对形式返回结果。

    Returns Promise<MemberScoreArray>

zrevrangebylex

    • Redis官方文档https://redis.io/commands/zrevrangebylex
    • 起始版本:2.8.9
    • 时间复杂度:O(log(N)+M) N 为排序集中的成员数量,M 为需要移除的成员数量。
      如果 M 始终是个常量(比如使用 limit 限制始终返回前 10 个元素),此时可以认为复杂度为 O(log(N))。

    有时为了获取一个字典序排序的排序集,会将所有成员以相同的分数存入排序集中,此时可以用 ZREVRANGEBYLEX 返回按照逆字典序排列在 min 和 max 中间的成员。

    除了倒序排列,ZREVRANGEBYLEX 和 ZRANGEBYLEX 命令行为一致。

    注意:6.2.0 版本开始,ZRANGE 可以通过参数 reverse 和 by:BYLEX 来实现 ZREVRANGEBYLEX。在之后的版本中,ZREVRANGEBYLEX可能会被废弃。

    返回值

    数组形式返回指定范围内的成员。

    例子:

    await client.zadd('zset', { a: 0, b: 0, c: 0, d: 0, e: 0, f: 0, g: 0 })
    // 7
    await client.zrevrangebylex('zset', '[c', '-')
    // ["c", "b", "a"]
    await client.zrevrangebylex('zset', '(c', '-')
    // ["b", "a"]
    await client.zrevrangebylex('zset', '(g', '[aaa')
    // ["f", "e", "d", "c", "b"]
    

    Parameters

    • key: string | Buffer
    • min: ZsetRangeMemberMin

      选取范围的最小值。

    • max: ZsetRangeMemberMin

      选取范围的最大值。

    • Optional limit: [number, number]

      限制返回成员数量,格式为 offset, count。

    Returns Promise<MemberArray>

zrevrangebyscore

    • Redis官方文档https://redis.io/commands/zrevrangebyscore
    • 起始版本:2.2.0
    • 时间复杂度:O(log(N)+M) N 为排序集中的成员数量,M 为需要移除的成员数量。
      如果 M 始终是个常量(比如使用 limit 限制始终返回前 10 个元素),此时可以认为复杂度为 O(log(N))。

    返回排序集中介于 min 和 max 间的全部成员。跟 | ZRANGEBYSCORE 命令不同的是,此命令行为默认从高到低排列。

    具有相同分数的成员按照逆字典序排列。

    注意:6.2.0 版本开始,ZRANGE 可以通过参数 reverse 和 by:BYSCORE 来实现 ZREVRANGEBYLEX。在之后的版本中,ZREVRANGEBYLEX可能会被废弃。

    返回值

    数组形式返回指定范围内的成员。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrevrangebyscore('zset', '+inf', '-inf')
    // ["three", "two", "one"]
    await client.zrevrangebyscore('zset', '2', '1')
    // ["two", "one"]
    await client.zrevrangebyscore('zset', '2', '(1')
    // ["two"]
    await client.zrevrangebyscore('zset', '(2', '(1')
    // []
    

    Parameters

    Returns Promise<MemberScoreArray>

    • Redis官方文档https://redis.io/commands/zrevrangebyscore
    • 起始版本:2.2.0
    • 时间复杂度:O(log(N)+M) N 为排序集中的成员数量,M 为需要移除的成员数量。
      如果 M 始终是个常量(比如使用 limit 限制始终返回前 10 个元素),此时可以认为复杂度为 O(log(N))。

    返回排序集中介于 min 和 max 间的全部成员。跟 | ZRANGEBYSCORE 命令不同的是,此命令行为默认从高到低排列。

    具有相同分数的成员按照逆字典序排列。

    注意:6.2.0 版本开始,ZRANGE 可以通过参数 reverse 和 by:BYSCORE 来实现 ZREVRANGEBYLEX。在之后的版本中,ZREVRANGEBYLEX可能会被废弃。

    返回值

    数组形式返回指定范围内的成员。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrevrangebyscore('zset', '+inf', '-inf')
    // ["three", "two", "one"]
    await client.zrevrangebyscore('zset', '2', '1')
    // ["two", "one"]
    await client.zrevrangebyscore('zset', '2', '(1')
    // ["two"]
    await client.zrevrangebyscore('zset', '(2', '(1')
    // []
    

    Parameters

    • key: string | Buffer
    • min: ZsetRangeScoreMin

      选取范围的最小值。

    • max: ZsetRangeScoreMin

      选取范围的最大值。

    • withscores: true

      以 member/score 对形式返回结果。

    Returns Promise<MemberScoreArray>

    • Redis官方文档https://redis.io/commands/zrevrangebyscore
    • 起始版本:2.2.0
    • 时间复杂度:O(log(N)+M) N 为排序集中的成员数量,M 为需要移除的成员数量。
      如果 M 始终是个常量(比如使用 limit 限制始终返回前 10 个元素),此时可以认为复杂度为 O(log(N))。

    返回排序集中介于 min 和 max 间的全部成员。跟 | ZRANGEBYSCORE 命令不同的是,此命令行为默认从高到低排列。

    具有相同分数的成员按照逆字典序排列。

    注意:6.2.0 版本开始,ZRANGE 可以通过参数 reverse 和 by:BYSCORE 来实现 ZREVRANGEBYLEX。在之后的版本中,ZREVRANGEBYLEX可能会被废弃。

    返回值

    数组形式返回指定范围内的成员。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrevrangebyscore('zset', '+inf', '-inf')
    // ["three", "two", "one"]
    await client.zrevrangebyscore('zset', '2', '1')
    // ["two", "one"]
    await client.zrevrangebyscore('zset', '2', '(1')
    // ["two"]
    await client.zrevrangebyscore('zset', '(2', '(1')
    // []
    

    Parameters

    • key: string | Buffer
    • min: ZsetRangeScoreMin

      选取范围的最小值。

    • max: ZsetRangeScoreMin

      选取范围的最大值。

    • limit: [number, number]

      限制返回成员数量,格式为 offset, count。

    Returns Promise<(string | Buffer)[]>

    • Redis官方文档https://redis.io/commands/zrevrangebyscore
    • 起始版本:2.2.0
    • 时间复杂度:O(log(N)+M) N 为排序集中的成员数量,M 为需要移除的成员数量。
      如果 M 始终是个常量(比如使用 limit 限制始终返回前 10 个元素),此时可以认为复杂度为 O(log(N))。

    返回排序集中介于 min 和 max 间的全部成员。跟 | ZRANGEBYSCORE 命令不同的是,此命令行为默认从高到低排列。

    具有相同分数的成员按照逆字典序排列。

    注意:6.2.0 版本开始,ZRANGE 可以通过参数 reverse 和 by:BYSCORE 来实现 ZREVRANGEBYLEX。在之后的版本中,ZREVRANGEBYLEX可能会被废弃。

    返回值

    数组形式返回指定范围内的成员。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrevrangebyscore('zset', '+inf', '-inf')
    // ["three", "two", "one"]
    await client.zrevrangebyscore('zset', '2', '1')
    // ["two", "one"]
    await client.zrevrangebyscore('zset', '2', '(1')
    // ["two"]
    await client.zrevrangebyscore('zset', '(2', '(1')
    // []
    

    Parameters

    • key: string | Buffer
    • min: ZsetRangeScoreMin

      选取范围的最小值。

    • max: ZsetRangeScoreMin

      选取范围的最大值。

    • limit: [number, number]

      限制返回成员数量,格式为 offset, count。

    • withscores: true

      以 member/score 对形式返回结果。

    Returns Promise<MemberScoreArray>

zrevrank

  • zrevrank(key: string | Buffer, member: string | Buffer): Promise<null | number>
  • 返回 member 在排序集中的顺位,排序规则为按照 score 从高到低。顺位是从 0 开始计数的,也就是说 0 表示最高的位。

    当需要获取成员分数从低到高的顺位时,使用 ZRANK 命令。

    返回值

    • 如果 member 存在,则返回整型表示的顺位。
    • 如果 member 不存在,返回 null。

    例子:

    await client.zadd('zset', { one: 1, two: 2, three: 3 })
    // 3
    await client.zrevrank('zset', 'one')
    // 2
    await client.zrevrank('zset', 'four')
    // null
    

    Parameters

    • key: string | Buffer
    • member: string | Buffer

    Returns Promise<null | number>

zscan

zscore

  • zscore(key: string | Buffer, member: string | Buffer): Promise<`${number}`>
  • 返回排序集中指定成员的分数。
    如果 key 不存在或者 member 不存在,返回 null。

    返回值

    返回字符串形式的双精度浮点数。

    例子:

    await client.zadd('zset', { one: 1 })
    // 1
    await client.zscore('zset', 'one')
    // "1"
    

    Parameters

    • key: string | Buffer
    • member: string | Buffer

    Returns Promise<`${number}`>

zunion

    • Redis官方文档https://redis.io/commands/zunion
    • 起始版本:6.2.0
    • 时间复杂度:O(N)+O(M*log(M)) N 是全部输入集的大小的和,M 是结果集的大小。

    这个命令类似 ZUNIONSTORE 命令,区别是 ZUNION 不会存储结果,而是将结果返回到客户端。

    具体参数选项的语义请参考 ZUNIONSTORE 命令。

    返回值

    数组形式返回输入集的并集。
    提供 withscores 参数会返回 member/score 对。

    例子:

    await client.zadd('zset1', { one: 1, two: 2 })
    // 2
    await client.zadd('zset2', { one: 1, two: 2, three: 3 })
    // 3
    await client.zunion(['zset1', 'zset2'])
    // ["one", "two", "three"]
    await client.zunion(['zset1', 'zset2'], true)
    // ["one", "2", "three", "3", "two", "4"]
    

    Type parameters

    • T: [string | Buffer, ...(string | Buffer)[]]

    Parameters

    Returns Promise<(string | Buffer)[]>

    • Redis官方文档https://redis.io/commands/zunion
    • 起始版本:6.2.0
    • 时间复杂度:O(N)+O(M*log(M)) N 是全部输入集的大小的和,M 是结果集的大小。

    这个命令类似 ZUNIONSTORE 命令,区别是 ZUNION 不会存储结果,而是将结果返回到客户端。

    具体参数选项的语义请参考 ZUNIONSTORE 命令。

    返回值

    数组形式返回输入集的并集。
    提供 withscores 参数会返回 member/score 对。

    例子:

    await client.zadd('zset1', { one: 1, two: 2 })
    // 2
    await client.zadd('zset2', { one: 1, two: 2, three: 3 })
    // 3
    await client.zunion(['zset1', 'zset2'])
    // ["one", "two", "three"]
    await client.zunion(['zset1', 'zset2'], true)
    // ["one", "2", "three", "3", "two", "4"]
    

    Type parameters

    • T: [string | Buffer, ...(string | Buffer)[]]

    Parameters

    • keys: T
    • withscores: true

      以 member/score 对形式返回结果。

    • Optional options: ZunionOptions<T>

    Returns Promise<MemberScoreArray>

zunionstore

  • zunionstore<T>(destination: string | Buffer, keys: [string | Buffer, ...(string | Buffer)[]], options?: ZinterOptions<T>): Promise<number>
  • 计算给定的排序集的并集,并将结果存入 destination 中。

    结果集中成员的分数,默认是该成员在所有输入排序集中的分数的和。

    使用 weights 选项可以设置输入集的权重因子。意思是输入集中的元素传递给聚合函数前会先乘以对应的权重。

    使用 aggregate 选项可以指定结果集中的 score 计算方式。默认是 'SUM' 也就是求和,可以更改为 'MIN' 或者 'MAX' 分别表示取最小值和最大值。

    如果 destination 已经存在则会被重写。

    返回值,

    例子:

    await client.zadd('zset1', { one: 1, two: 2 })
    // 2
    await client.zadd('zset2', { one: 1, two: 2, three: 3 })
    // 3
    await client.zunionstore('out', ['zset1', 'zset2'], { weights: [2, 3] })
    // 3
    await client.zrange('out', { min: 0, max: -1 }, true)
    // ["one", "5", "three", "9", "two", "10"]
    

    Type parameters

    • T: [string | Buffer, ...(string | Buffer)[]]

    Parameters

    • destination: string | Buffer
    • keys: [string | Buffer, ...(string | Buffer)[]]
    • Optional options: ZinterOptions<T>

    Returns Promise<number>

Generated using TypeDoc