Module: Redis::Commands::SortedSets

Included in:
Redis::Commands
Defined in:
lib/redis/commands/sorted_sets.rb

Instance Method Summary collapse

Instance Method Details

#bzmpop(timeout, *keys, modifier: "MIN", count: nil) ⇒ Array<String, Array<String, Float>>

Removes and returns up to count members with scores in the sorted set stored at key.

Examples:

Popping a member

redis.bzmpop('zset')
#=> ['zset', ['a', 1.0]]

With count option

redis.bzmpop('zset', count: 2)
#=> ['zset', [['a', 1.0], ['b', 2.0]]

Raises:

  • (ArgumentError)


188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
# File 'lib/redis/commands/sorted_sets.rb', line 188

def bzmpop(timeout, *keys, modifier: "MIN", count: nil)
  raise ArgumentError, "Pick either MIN or MAX" unless modifier == "MIN" || modifier == "MAX"

  args = [:bzmpop, timeout, keys.size, *keys, modifier]
  args << "COUNT" << Integer(count) if count

  send_blocking_command(args, timeout) do |response|
    response&.map do |entry|
      case entry
      when String then entry
      when Array then entry.map { |pair| FloatifyPairs.call(pair) }.flatten(1)
      end
    end
  end
end

#bzpopmax(*args) ⇒ Array<String, String, Float>?

Removes and returns up to count members with the highest scores in the sorted set stored at keys,

or block until one is available.

Examples:

Popping a member from a sorted set

redis.bzpopmax('zset', 1)
#=> ['zset', 'b', 2.0]

Popping a member from multiple sorted sets

redis.bzpopmax('zset1', 'zset2', 1)
#=> ['zset1', 'b', 2.0]


251
252
253
254
255
# File 'lib/redis/commands/sorted_sets.rb', line 251

def bzpopmax(*args)
  _bpop(:bzpopmax, args) do |reply|
    reply.is_a?(Array) ? [reply[0], reply[1], Floatify.call(reply[2])] : reply
  end
end

#bzpopmin(*args) ⇒ Array<String, String, Float>?

Removes and returns up to count members with the lowest scores in the sorted set stored at keys,

or block until one is available.

Examples:

Popping a member from a sorted set

redis.bzpopmin('zset', 1)
#=> ['zset', 'a', 1.0]

Popping a member from multiple sorted sets

redis.bzpopmin('zset1', 'zset2', 1)
#=> ['zset1', 'a', 1.0]


272
273
274
275
276
# File 'lib/redis/commands/sorted_sets.rb', line 272

def bzpopmin(*args)
  _bpop(:bzpopmin, args) do |reply|
    reply.is_a?(Array) ? [reply[0], reply[1], Floatify.call(reply[2])] : reply
  end
end

#zadd(key, *args, nx: nil, xx: nil, lt: nil, gt: nil, ch: nil, incr: nil) ⇒ Boolean, ...

Add one or more members to a sorted set, or update the score for members that already exist.

Examples:

Add a single ‘[score, member]` pair to a sorted set

redis.zadd("zset", 32.0, "member")

Add an array of ‘[score, member]` pairs to a sorted set

redis.zadd("zset", [[32.0, "a"], [64.0, "b"]])


53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
# File 'lib/redis/commands/sorted_sets.rb', line 53

def zadd(key, *args, nx: nil, xx: nil, lt: nil, gt: nil, ch: nil, incr: nil)
  command = [:zadd, key]
  command << "NX" if nx
  command << "XX" if xx
  command << "LT" if lt
  command << "GT" if gt
  command << "CH" if ch
  command << "INCR" if incr

  if args.size == 1 && args[0].is_a?(Array)
    members_to_add = args[0]
    return 0 if members_to_add.empty?

    # Variadic: return float if INCR, integer if !INCR
    send_command(command + members_to_add, &(incr ? Floatify : nil))
  elsif args.size == 2
    # Single pair: return float if INCR, boolean if !INCR
    send_command(command + args, &(incr ? Floatify : Boolify))
  else
    raise ArgumentError, "wrong number of arguments"
  end
end

#zcard(key) ⇒ Integer

Get the number of members in a sorted set.

Examples:

redis.zcard("zset")
  # => 4


14
15
16
# File 'lib/redis/commands/sorted_sets.rb', line 14

def zcard(key)
  send_command([:zcard, key])
end

#zcount(key, min, max) ⇒ Integer

Count the members in a sorted set with scores within the given values.

Examples:

Count members with score ‘>= 5` and `< 100`

redis.zcount("zset", "5", "(100")
  # => 2

Count members with scores ‘> 5`

redis.zcount("zset", "(5", "+inf")
  # => 2


678
679
680
# File 'lib/redis/commands/sorted_sets.rb', line 678

def zcount(key, min, max)
  send_command([:zcount, key, min, max])
end

#zdiff(*keys, with_scores: false) ⇒ Array<String>, Array<[String, Float]>

Return the difference between the first and all successive input sorted sets

Examples:

redis.zadd("zsetA", [[1.0, "v1"], [2.0, "v2"]])
redis.zadd("zsetB", [[3.0, "v2"], [2.0, "v3"]])
redis.zdiff("zsetA", "zsetB")
  => ["v1"]

With scores

redis.zadd("zsetA", [[1.0, "v1"], [2.0, "v2"]])
redis.zadd("zsetB", [[3.0, "v2"], [2.0, "v3"]])
redis.zdiff("zsetA", "zsetB", :with_scores => true)
  => [["v1", 1.0]]


787
788
789
# File 'lib/redis/commands/sorted_sets.rb', line 787

def zdiff(*keys, with_scores: false)
  _zsets_operation(:zdiff, *keys, with_scores: with_scores)
end

#zdiffstore(*args) ⇒ Integer

Compute the difference between the first and all successive input sorted sets and store the resulting sorted set in a new key

Examples:

redis.zadd("zsetA", [[1.0, "v1"], [2.0, "v2"]])
redis.zadd("zsetB", [[3.0, "v2"], [2.0, "v3"]])
redis.zdiffstore("zsetA", "zsetB")
  # => 1


803
804
805
# File 'lib/redis/commands/sorted_sets.rb', line 803

def zdiffstore(*args)
  _zsets_operation_store(:zdiffstore, *args)
end

#zincrby(key, increment, member) ⇒ Float

Increment the score of a member in a sorted set.

Examples:

redis.zincrby("zset", 32.0, "a")
  # => 64.0


86
87
88
# File 'lib/redis/commands/sorted_sets.rb', line 86

def zincrby(key, increment, member)
  send_command([:zincrby, key, increment, member], &Floatify)
end

#zinter(*args) ⇒ Array<String>, Array<[String, Float]>

Return the intersection of multiple sorted sets

Examples:

Retrieve the intersection of ‘2*zsetA` and `1*zsetB`

redis.zinter("zsetA", "zsetB", :weights => [2.0, 1.0])
  # => ["v1", "v2"]

Retrieve the intersection of ‘2*zsetA` and `1*zsetB`, and their scores

redis.zinter("zsetA", "zsetB", :weights => [2.0, 1.0], :with_scores => true)
  # => [["v1", 3.0], ["v2", 6.0]]


701
702
703
# File 'lib/redis/commands/sorted_sets.rb', line 701

def zinter(*args)
  _zsets_operation(:zinter, *args)
end

#zinterstore(*args) ⇒ Integer

Intersect multiple sorted sets and store the resulting sorted set in a new key.

Examples:

Compute the intersection of ‘2*zsetA` with `1*zsetB`, summing their scores

redis.zinterstore("zsetC", ["zsetA", "zsetB"], :weights => [2.0, 1.0], :aggregate => "sum")
  # => 4


720
721
722
# File 'lib/redis/commands/sorted_sets.rb', line 720

def zinterstore(*args)
  _zsets_operation_store(:zinterstore, *args)
end

#zlexcount(key, min, max) ⇒ Integer

Count the members, with the same score in a sorted set, within the given lexicographical range.

Examples:

Count members matching a

redis.zlexcount("zset", "[a", "[a\xff")
  # => 1

Count members matching a-z

redis.zlexcount("zset", "[a", "[z\xff")
  # => 26


509
510
511
# File 'lib/redis/commands/sorted_sets.rb', line 509

def zlexcount(key, min, max)
  send_command([:zlexcount, key, min, max])
end

#zmpop(*keys, modifier: "MIN", count: nil) ⇒ Array<String, Array<String, Float>>

Removes and returns up to count members with scores in the sorted set stored at key.

Examples:

Popping a member

redis.zmpop('zset')
#=> ['zset', ['a', 1.0]]

With count option

redis.zmpop('zset', count: 2)
#=> ['zset', [['a', 1.0], ['b', 2.0]]

Raises:

  • (ArgumentError)


220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
# File 'lib/redis/commands/sorted_sets.rb', line 220

def zmpop(*keys, modifier: "MIN", count: nil)
  raise ArgumentError, "Pick either MIN or MAX" unless modifier == "MIN" || modifier == "MAX"

  args = [:zmpop, keys.size, *keys, modifier]
  args << "COUNT" << Integer(count) if count

  send_command(args) do |response|
    response&.map do |entry|
      case entry
      when String then entry
      when Array then entry.map { |pair| FloatifyPairs.call(pair) }.flatten(1)
      end
    end
  end
end

#zmscore(key, *members) ⇒ Array<Float>

Get the scores associated with the given members in a sorted set.

Examples:

Get the scores for members “a” and “b”

redis.zmscore("zset", "a", "b")
  # => [32.0, 48.0]


300
301
302
303
304
# File 'lib/redis/commands/sorted_sets.rb', line 300

def zmscore(key, *members)
  send_command([:zmscore, key, *members]) do |reply|
    reply.map(&Floatify)
  end
end

#zpopmax(key, count = nil) ⇒ Array<String, Float>+

Removes and returns up to count members with the highest scores in the sorted set stored at key.

Examples:

Popping a member

redis.zpopmax('zset')
#=> ['b', 2.0]

With count option

redis.zpopmax('zset', 2)
#=> [['b', 2.0], ['a', 1.0]]


138
139
140
141
142
143
144
145
# File 'lib/redis/commands/sorted_sets.rb', line 138

def zpopmax(key, count = nil)
  command = [:zpopmax, key]
  command << Integer(count) if count
  send_command(command) do |members|
    members = FloatifyPairs.call(members)
    count.to_i > 1 ? members : members.first
  end
end

#zpopmin(key, count = nil) ⇒ Array<String, Float>+

Removes and returns up to count members with the lowest scores in the sorted set stored at key.

Examples:

Popping a member

redis.zpopmin('zset')
#=> ['a', 1.0]

With count option

redis.zpopmin('zset', 2)
#=> [['a', 1.0], ['b', 2.0]]


161
162
163
164
165
166
167
168
# File 'lib/redis/commands/sorted_sets.rb', line 161

def zpopmin(key, count = nil)
  command = [:zpopmin, key]
  command << Integer(count) if count
  send_command(command) do |members|
    members = FloatifyPairs.call(members)
    count.to_i > 1 ? members : members.first
  end
end

#zrandmember(key, count = nil, withscores: false, with_scores: withscores) ⇒ nil, ...

Get one or more random members from a sorted set.

Examples:

Get one random member

redis.zrandmember("zset")
  # => "a"

Get multiple random members

redis.zrandmember("zset", 2)
  # => ["a", "b"]

Get multiple random members with scores

redis.zrandmember("zset", 2, with_scores: true)
  # => [["a", 2.0], ["b", 3.0]]


328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
# File 'lib/redis/commands/sorted_sets.rb', line 328

def zrandmember(key, count = nil, withscores: false, with_scores: withscores)
  if with_scores && count.nil?
    raise ArgumentError, "count argument must be specified"
  end

  args = [:zrandmember, key]
  args << Integer(count) if count

  if with_scores
    args << "WITHSCORES"
    block = FloatifyPairs
  end

  send_command(args, &block)
end

#zrange(key, start, stop, byscore: false, by_score: byscore, bylex: false, by_lex: bylex, rev: false, limit: nil, withscores: false, with_scores: withscores) ⇒ Array<String>, Array<[String, Float]>

Return a range of members in a sorted set, by index, score or lexicographical ordering.

Examples:

Retrieve all members from a sorted set, by index

redis.zrange("zset", 0, -1)
  # => ["a", "b"]

Retrieve all members and their scores from a sorted set

redis.zrange("zset", 0, -1, :with_scores => true)
  # => [["a", 32.0], ["b", 64.0]]


367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
# File 'lib/redis/commands/sorted_sets.rb', line 367

def zrange(key, start, stop, byscore: false, by_score: byscore, bylex: false, by_lex: bylex,
           rev: false, limit: nil, withscores: false, with_scores: withscores)

  if by_score && by_lex
    raise ArgumentError, "only one of :by_score or :by_lex can be specified"
  end

  args = [:zrange, key, start, stop]

  if by_score
    args << "BYSCORE"
  elsif by_lex
    args << "BYLEX"
  end

  args << "REV" if rev

  if limit
    args << "LIMIT"
    args.concat(limit.map { |l| Integer(l) })
  end

  if with_scores
    args << "WITHSCORES"
    block = FloatifyPairs
  end

  send_command(args, &block)
end

#zrangebylex(key, min, max, limit: nil) ⇒ Array<String>, Array<[String, Float]>

Return a range of members with the same score in a sorted set, by lexicographical ordering

Examples:

Retrieve members matching a

redis.zrangebylex("zset", "[a", "[a\xff")
  # => ["aaren", "aarika", "abagael", "abby"]

Retrieve the first 2 members matching a

redis.zrangebylex("zset", "[a", "[a\xff", :limit => [0, 2])
  # => ["aaren", "aarika"]


534
535
536
537
538
539
540
541
542
543
# File 'lib/redis/commands/sorted_sets.rb', line 534

def zrangebylex(key, min, max, limit: nil)
  args = [:zrangebylex, key, min, max]

  if limit
    args << "LIMIT"
    args.concat(limit.map { |l| Integer(l) })
  end

  send_command(args)
end

#zrangebyscore(key, min, max, withscores: false, with_scores: withscores, limit: nil) ⇒ Array<String>, Array<[String, Float]>

Return a range of members in a sorted set, by score.

Examples:

Retrieve members with score ‘>= 5` and `< 100`

redis.zrangebyscore("zset", "5", "(100")
  # => ["a", "b"]

Retrieve the first 2 members with score ‘>= 0`

redis.zrangebyscore("zset", "0", "+inf", :limit => [0, 2])
  # => ["a", "b"]

Retrieve members and their scores with scores ‘> 5`

redis.zrangebyscore("zset", "(5", "+inf", :with_scores => true)
  # => [["a", 32.0], ["b", 64.0]]


594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
# File 'lib/redis/commands/sorted_sets.rb', line 594

def zrangebyscore(key, min, max, withscores: false, with_scores: withscores, limit: nil)
  args = [:zrangebyscore, key, min, max]

  if with_scores
    args << "WITHSCORES"
    block = FloatifyPairs
  end

  if limit
    args << "LIMIT"
    args.concat(limit.map { |l| Integer(l) })
  end

  send_command(args, &block)
end

#zrangestore(dest_key, src_key, start, stop, byscore: false, by_score: byscore, bylex: false, by_lex: bylex, rev: false, limit: nil) ⇒ Integer

Select a range of members in a sorted set, by index, score or lexicographical ordering and store the resulting sorted set in a new key.

Examples:

redis.zadd("foo", [[1.0, "s1"], [2.0, "s2"], [3.0, "s3"]])
redis.zrangestore("bar", "foo", 0, 1)
  # => 2
redis.zrange("bar", 0, -1)
  # => ["s1", "s2"]

See Also:



409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
# File 'lib/redis/commands/sorted_sets.rb', line 409

def zrangestore(dest_key, src_key, start, stop, byscore: false, by_score: byscore,
                bylex: false, by_lex: bylex, rev: false, limit: nil)
  if by_score && by_lex
    raise ArgumentError, "only one of :by_score or :by_lex can be specified"
  end

  args = [:zrangestore, dest_key, src_key, start, stop]

  if by_score
    args << "BYSCORE"
  elsif by_lex
    args << "BYLEX"
  end

  args << "REV" if rev

  if limit
    args << "LIMIT"
    args.concat(limit.map { |l| Integer(l) })
  end

  send_command(args)
end

#zrank(key, member) ⇒ Integer

Determine the index of a member in a sorted set.



460
461
462
# File 'lib/redis/commands/sorted_sets.rb', line 460

def zrank(key, member)
  send_command([:zrank, key, member])
end

#zrem(key, member) ⇒ Boolean, Integer

Remove one or more members from a sorted set.

Examples:

Remove a single member from a sorted set

redis.zrem("zset", "a")

Remove an array of members from a sorted set

redis.zrem("zset", ["a", "b"])


107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
# File 'lib/redis/commands/sorted_sets.rb', line 107

def zrem(key, member)
  if member.is_a?(Array)
    members_to_remove = member
    return 0 if members_to_remove.empty?
  end

  send_command([:zrem, key, member]) do |reply|
    if member.is_a? Array
      # Variadic: return integer
      reply
    else
      # Single argument: return boolean
      Boolify.call(reply)
    end
  end
end

#zremrangebyrank(key, start, stop) ⇒ Integer

Remove all members in a sorted set within the given indexes.

Examples:

Remove first 5 members

redis.zremrangebyrank("zset", 0, 4)
  # => 5

Remove last 5 members

redis.zremrangebyrank("zset", -5, -1)
  # => 5


487
488
489
# File 'lib/redis/commands/sorted_sets.rb', line 487

def zremrangebyrank(key, start, stop)
  send_command([:zremrangebyrank, key, start, stop])
end

#zremrangebyscore(key, min, max) ⇒ Integer

Remove all members in a sorted set within the given scores.

Examples:

Remove members with score ‘>= 5` and `< 100`

redis.zremrangebyscore("zset", "5", "(100")
  # => 2

Remove members with scores ‘> 5`

redis.zremrangebyscore("zset", "(5", "+inf")
  # => 2


657
658
659
# File 'lib/redis/commands/sorted_sets.rb', line 657

def zremrangebyscore(key, min, max)
  send_command([:zremrangebyscore, key, min, max])
end

#zrevrange(key, start, stop, withscores: false, with_scores: withscores) ⇒ Object

Return a range of members in a sorted set, by index, with scores ordered from high to low.

Examples:

Retrieve all members from a sorted set

redis.zrevrange("zset", 0, -1)
  # => ["b", "a"]

Retrieve all members and their scores from a sorted set

redis.zrevrange("zset", 0, -1, :with_scores => true)
  # => [["b", 64.0], ["a", 32.0]]

See Also:



444
445
446
447
448
449
450
451
452
453
# File 'lib/redis/commands/sorted_sets.rb', line 444

def zrevrange(key, start, stop, withscores: false, with_scores: withscores)
  args = [:zrevrange, key, Integer(start), Integer(stop)]

  if with_scores
    args << "WITHSCORES"
    block = FloatifyPairs
  end

  send_command(args, &block)
end

#zrevrangebylex(key, max, min, limit: nil) ⇒ Object

Return a range of members with the same score in a sorted set, by reversed lexicographical ordering. Apart from the reversed ordering, #zrevrangebylex is similar to #zrangebylex.

Examples:

Retrieve members matching a

redis.zrevrangebylex("zset", "[a", "[a\xff")
  # => ["abbygail", "abby", "abagael", "aaren"]

Retrieve the last 2 members matching a

redis.zrevrangebylex("zset", "[a", "[a\xff", :limit => [0, 2])
  # => ["abbygail", "abby"]

See Also:



556
557
558
559
560
561
562
563
564
565
# File 'lib/redis/commands/sorted_sets.rb', line 556

def zrevrangebylex(key, max, min, limit: nil)
  args = [:zrevrangebylex, key, max, min]

  if limit
    args << "LIMIT"
    args.concat(limit.map { |l| Integer(l) })
  end

  send_command(args)
end

#zrevrangebyscore(key, max, min, withscores: false, with_scores: withscores, limit: nil) ⇒ Object

Return a range of members in a sorted set, by score, with scores ordered from high to low.

Examples:

Retrieve members with score ‘< 100` and `>= 5`

redis.zrevrangebyscore("zset", "(100", "5")
  # => ["b", "a"]

Retrieve the first 2 members with score ‘<= 0`

redis.zrevrangebyscore("zset", "0", "-inf", :limit => [0, 2])
  # => ["b", "a"]

Retrieve members and their scores with scores ‘> 5`

redis.zrevrangebyscore("zset", "+inf", "(5", :with_scores => true)
  # => [["b", 64.0], ["a", 32.0]]

See Also:



624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
# File 'lib/redis/commands/sorted_sets.rb', line 624

def zrevrangebyscore(key, max, min, withscores: false, with_scores: withscores, limit: nil)
  args = [:zrevrangebyscore, key, max, min]

  if with_scores
    args << "WITHSCORES"
    block = FloatifyPairs
  end

  if limit
    args << "LIMIT"
    args.concat(limit.map { |l| Integer(l) })
  end

  send_command(args, &block)
end

#zrevrank(key, member) ⇒ Integer

Determine the index of a member in a sorted set, with scores ordered from high to low.



470
471
472
# File 'lib/redis/commands/sorted_sets.rb', line 470

def zrevrank(key, member)
  send_command([:zrevrank, key, member])
end

#zscan(key, cursor, **options) ⇒ String, Array<[String, Float]>

Scan a sorted set

See the [Redis Server ZSCAN documentation](redis.io/docs/latest/commands/zscan/) for further details

Examples:

Retrieve the first batch of key/value pairs in a hash

redis.zscan("zset", 0)


822
823
824
825
826
# File 'lib/redis/commands/sorted_sets.rb', line 822

def zscan(key, cursor, **options)
  _scan(:zscan, cursor, [key], **options) do |reply|
    [reply[0], FloatifyPairs.call(reply[1])]
  end
end

#zscan_each(key, **options, &block) ⇒ Enumerator

Scan a sorted set

See the [Redis Server ZSCAN documentation](redis.io/docs/latest/commands/zscan/) for further details

Examples:

Retrieve all of the members/scores in a sorted set

redis.zscan_each("zset").to_a
# => [["key70", "70"], ["key80", "80"]]


841
842
843
844
845
846
847
848
849
850
# File 'lib/redis/commands/sorted_sets.rb', line 841

def zscan_each(key, **options, &block)
  return to_enum(:zscan_each, key, **options) unless block_given?

  cursor = 0
  loop do
    cursor, values = zscan(key, cursor, **options)
    values.each(&block)
    break if cursor == "0"
  end
end

#zscore(key, member) ⇒ Float

Get the score associated with the given member in a sorted set.

Examples:

Get the score for member “a”

redis.zscore("zset", "a")
  # => 32.0


287
288
289
# File 'lib/redis/commands/sorted_sets.rb', line 287

def zscore(key, member)
  send_command([:zscore, key, member], &Floatify)
end

#zunion(*args) ⇒ Array<String>, Array<[String, Float]>

Return the union of multiple sorted sets

Examples:

Retrieve the union of ‘2*zsetA` and `1*zsetB`

redis.zunion("zsetA", "zsetB", :weights => [2.0, 1.0])
  # => ["v1", "v2"]

Retrieve the union of ‘2*zsetA` and `1*zsetB`, and their scores

redis.zunion("zsetA", "zsetB", :weights => [2.0, 1.0], :with_scores => true)
  # => [["v1", 3.0], ["v2", 6.0]]


744
745
746
# File 'lib/redis/commands/sorted_sets.rb', line 744

def zunion(*args)
  _zsets_operation(:zunion, *args)
end

#zunionstore(*args) ⇒ Integer

Add multiple sorted sets and store the resulting sorted set in a new key.

Examples:

Compute the union of ‘2*zsetA` with `1*zsetB`, summing their scores

redis.zunionstore("zsetC", ["zsetA", "zsetB"], :weights => [2.0, 1.0], :aggregate => "sum")
  # => 8


762
763
764
# File 'lib/redis/commands/sorted_sets.rb', line 762

def zunionstore(*args)
  _zsets_operation_store(:zunionstore, *args)
end