Module: Valkey::Commands::SortedSetCommands

Included in:
Valkey::Commands
Defined in:
lib/valkey/commands/sorted_set_commands.rb

Instance Method Summary collapse

Instance Method Details

#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

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

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

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

Parameters:

  • key (String)
  • args ([Float, String], Array<[Float, String]>) —

    • a single ‘[score, member]` pair

    • an array of ‘[score, member]` pairs

  • options (Hash) —

    • ‘:xx => true`: Only update elements that already exist (never

    add elements)

    • ‘:nx => true`: Don’t update already existing elements (always

    add new elements)

    • ‘:lt => true`: Only update existing elements if the new score

    is less than the current score

    • ‘:gt => true`: Only update existing elements if the new score

    is greater than the current score

    • ‘:ch => true`: Modify the return value from the number of new

    elements added, to the total number of elements changed (CH is an abbreviation of changed); changed elements are new elements added and elements already existing for which the score was updated

    • ‘:incr => true`: When this option is specified ZADD acts like

    ZINCRBY; only one score-element pair can be specified in this mode

Returns:

  • (Boolean, Integer, Float) —

    • ‘Boolean` when a single pair is specified, holding whether or not it was

    added to the sorted set.

    • ‘Integer` when an array of pairs is specified, holding the number of

    pairs that were added to the sorted set.

    • ‘Float` when option :incr is specified, holding the score of the member

    after incrementing it.



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

def zadd(key, *args, nx: nil, xx: nil, lt: nil, gt: nil, ch: nil, incr: nil)
  command_args = [key]
  command_args << "NX" if nx
  command_args << "XX" if xx
  command_args << "LT" if lt
  command_args << "GT" if gt
  command_args << "CH" if ch
  command_args << "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(RequestType::Z_ADD, command_args + members_to_add.flatten, &(incr ? Utils::Floatify : nil))
  elsif args.size == 2
    # Single pair: return float if INCR, boolean if !INCR
    send_command(RequestType::Z_ADD, command_args + args.flatten.flatten, &(incr ? Utils::Floatify : Utils::Boolify))
  else
    raise ArgumentError, "wrong number of arguments"
  end
end

#zcard(key) ⇒ Integer

Get the number of members in a sorted set.

Examples:

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

Parameters:

  • key (String)

Returns:

  • (Integer) 


14
15
16
 
# File 'lib/valkey/commands/sorted_set_commands.rb', line 14

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

#zincrby(key, increment, member) ⇒ Float

Increment the score of a member in a sorted set.

Examples:

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

Parameters:

  • key (String)
  • increment (Float)
  • member (String)

Returns:

  • (Float) —

    score of the member after incrementing it



86
87
88
 
# File 'lib/valkey/commands/sorted_set_commands.rb', line 86

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

#zrank(key, member, withscore: false, with_score: withscore) ⇒ Integer, [Integer, Float]

Determine the index of a member in a sorted set.

Examples:

Retrieve member rank

valkey.zrank("zset", "a")
  # => 3

Retrieve member rank with their score

valkey.zrank("zset", "a", :with_score => true)
  # => [3, 32.0]

Parameters:

  • key (String)
  • member (String)

Returns:

  • (Integer, [Integer, Float]) —

    • when ‘:with_score` is not specified, an Integer

    • when ‘:with_score` is specified, a `[rank, score]` pair



151
152
153
154
155
156
157
158
159
160
 
# File 'lib/valkey/commands/sorted_set_commands.rb', line 151

def zrank(key, member, withscore: false, with_score: withscore)
  args = [key, member]

  if with_score
    args << "WITHSCORE"
    block = Utils::FloatifyPair
  end

  send_command(RequestType::Z_RANK, args, &block)
end

#zrem(key, member) ⇒ Boolean, Integer

Remove one or more members from a sorted set.

Examples:

Remove a single member from a sorted set

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

Remove an array of members from a sorted set

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

Parameters:

  • key (String)
  • member (String, Array<String>) —

    • a single member

    • an array of members

Returns:

  • (Boolean, Integer) —

    • ‘Boolean` when a single member is specified, holding whether or not it

    was removed from the sorted set

    • ‘Integer` when an array of pairs is specified, holding the number of

    members that were removed to the sorted set



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/valkey/commands/sorted_set_commands.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(RequestType::Z_REM, [key, member].flatten) do |reply|
    if member.is_a? Array
      # Variadic: return integer
      reply
    else
      # Single argument: return boolean
      Utils::Boolify.call(reply)
    end
  end
end

#zrevrank(key, member, withscore: false, with_score: withscore) ⇒ Integer, [Integer, Float]

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

Examples:

Retrieve member rank

valkey.zrevrank("zset", "a")
  # => 3

Retrieve member rank with their score

valkey.zrevrank("zset", "a", :with_score => true)
  # => [3, 32.0]

Parameters:

  • key (String)
  • member (String)

Returns:

  • (Integer, [Integer, Float]) —

    • when ‘:with_score` is not specified, an Integer

    • when ‘:with_score` is specified, a `[rank, score]` pair



178
179
180
181
182
183
184
185
186
187
 
# File 'lib/valkey/commands/sorted_set_commands.rb', line 178

def zrevrank(key, member, withscore: false, with_score: withscore)
  args = [key, member]

  if with_score
    args << "WITHSCORE"
    block = Utils::FloatifyPair
  end

  send_command(RequestType::Z_REV_RANK, args, &block)
end

#zscore(key, member) ⇒ Float

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

Examples:

Get the score for member “a”

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

Parameters:

  • key (String)
  • member (String)

Returns:

  • (Float) —

    score of the member



132
133
134
 
# File 'lib/valkey/commands/sorted_set_commands.rb', line 132

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