class Redis

@deprecated The preferred way to create a new client object is using `#new`.

This method does not actually establish a connection to Redis,
in contrary to what you might expect.

# File lib/redis.rb, line 15
def self.connect(options = {})
  new(options)
end

Append a value to a key.

@param [String] key @param [String] value value to append @return [Fixnum] length of the string after appending

# File lib/redis.rb, line 884
def append(key, value)
  synchronize do |client|
    client.call([:append, key, value])
  end
end

Authenticate to the server.

@param [String] password must match the password specified in the

`requirepass` directive in the configuration file

@return [String] `OK`

# File lib/redis.rb, line 67
def auth(password)
  synchronize do |client|
    client.call([:auth, password])
  end
end

Asynchronously rewrite the append-only file.

@return [String] `OK`

# File lib/redis.rb, line 120
def bgrewriteaof
  synchronize do |client|
    client.call([:bgrewriteaof])
  end
end

Asynchronously save the dataset to disk.

@return [String] `OK`

# File lib/redis.rb, line 129
def bgsave
  synchronize do |client|
    client.call([:bgsave])
  end
end

Count the number of set bits in a range of the string value stored at key.

@param [String] key @param [Fixnum] start start index @param [Fixnum] stop stop index @return [Fixnum] the number of bits set to 1

# File lib/redis.rb, line 896
def bitcount(key, start = 0, stop = -1)
  synchronize do |client|
    client.call([:bitcount, key, start, stop])
  end
end

Perform a bitwise operation between strings and store the resulting string in a key.

@param [String] operation e.g. `and`, `or`, `xor`, `not` @param [String] destkey destination key @param [String, Array<String>] keys one or more source keys to perform `operation` @return [Fixnum] the length of the string stored in `destkey`

# File lib/redis.rb, line 908
def bitop(operation, destkey, *keys)
  synchronize do |client|
    client.call([:bitop, operation, destkey] + keys)
  end
end

Return the position of the first bit set to 1 or 0 in a string.

@param [String] key @param [Fixnum] bit whether to look for the first 1 or 0 bit @param [Fixnum] start start index @param [Fixnum] stop stop index @return [Fixnum] the position of the first 1/0 bit.

-1 if looking for 1 and it is not found or start and stop are given.

# File lib/redis.rb, line 922
def bitpos(key, bit, start=nil, stop=nil)
  if stop and not start
    raise(ArgumentError, 'stop parameter specified without start parameter')
  end

  synchronize do |client|
    command = [:bitpos, key, bit]
    command << start if start
    command << stop if stop
    client.call(command)
  end
end

Remove and get the first element in a list, or block until one is available.

@example With timeout

list, element = redis.blpop("list", :timeout => 5)
  # => nil on timeout
  # => ["list", "element"] on success

@example Without timeout

list, element = redis.blpop("list")
  # => ["list", "element"]

@example Blocking pop on multiple lists

list, element = redis.blpop(["list", "another_list"])
  # => ["list", "element"]

@param [String, Array<String>] keys one or more keys to perform the

blocking pop on

@param [Hash] options

- `:timeout => Fixnum`: timeout in seconds, defaults to no timeout

@return [nil, [String, String]]

- `nil` when the operation timed out
- tuple of the list that was popped from and element was popped otherwise

# File lib/redis.rb, line 1089
def blpop(*args)
  _bpop(:blpop, args)
end

Remove and get the last element in a list, or block until one is available.

@param [String, Array<String>] keys one or more keys to perform the

blocking pop on

@param [Hash] options

- `:timeout => Fixnum`: timeout in seconds, defaults to no timeout

@return [nil, [String, String]]

- `nil` when the operation timed out
- tuple of the list that was popped from and element was popped otherwise

@see blpop

# File lib/redis.rb, line 1105
def brpop(*args)
  _bpop(:brpop, args)
end

Pop a value from a list, push it to another list and return it; or block until one is available.

@param [String] source source key @param [String] destination destination key @param [Hash] options

- `:timeout => Fixnum`: timeout in seconds, defaults to no timeout

@return [nil, String]

- `nil` when the operation timed out
- the element was popped and pushed otherwise

# File lib/redis.rb, line 1120
def brpoplpush(source, destination, options = {})
  case options
  when Integer
    # Issue deprecation notice in obnoxious mode...
    options = { :timeout => options }
  end

  timeout = options[:timeout] || 0

  synchronize do |client|
    command = [:brpoplpush, source, destination, timeout]
    timeout += client.timeout if timeout > 0
    client.call_with_timeout(command, timeout)
  end
end

Get or set server configuration parameters.

@param [Symbol] action e.g. `:get`, `:set`, `:resetstat` @return [String, Hash] string reply, or hash when retrieving more than one

property with %x`CONFIG GET`

# File lib/redis.rb, line 140
def config(action, *args)
  synchronize do |client|
    client.call([:config, action] + args) do |reply|
      if reply.kind_of?(Array) && action == :get
        Hash[_pairify(reply)]
      else
        reply
      end
    end
  end
end

Test whether or not the client is connected

# File lib/redis.rb, line 53
def connected?
  @original_client.connected?
end

Return the number of keys in the selected database.

@return [Fixnum]

# File lib/redis.rb, line 155
def dbsize
  synchronize do |client|
    client.call([:dbsize])
  end
end

Decrement the integer value of a key by one.

@example

redis.decr("value")
  # => 4

@param [String] key @return [Fixnum] value after decrementing it

# File lib/redis.rb, line 587
def decr(key)
  synchronize do |client|
    client.call([:decr, key])
  end
end

Decrement the integer value of a key by the given number.

@example

redis.decrby("value", 5)
  # => 0

@param [String] key @param [Fixnum] decrement @return [Fixnum] value after decrementing it

# File lib/redis.rb, line 602
def decrby(key, decrement)
  synchronize do |client|
    client.call([:decrby, key, decrement])
  end
end

Delete one or more keys.

@param [String, Array<String>] keys @return [Fixnum] number of keys that were deleted

# File lib/redis.rb, line 419
def del(*keys)
  synchronize do |client|
    client.call([:del] + keys)
  end
end

Discard all commands issued after MULTI.

Only call this method when `#multi` was called *without* a block.

@return `“OK”`

@see multi @see exec

# File lib/redis.rb, line 2214
def discard
  synchronize do |client|
    client.call([:discard])
  end
end

Disconnect the client as quickly and silently as possible.

# File lib/redis.rb, line 58
def disconnect!
  @original_client.disconnect
end

Return a serialized version of the value stored at a key.

@param [String] key @return [String] serialized_value

# File lib/redis.rb, line 377
def dump(key)
  synchronize do |client|
    client.call([:dump, key])
  end
end

Echo the given string.

@param [String] value @return [String]

# File lib/redis.rb, line 97
def echo(value)
  synchronize do |client|
    client.call([:echo, value])
  end
end

Evaluate Lua script.

@example EVAL without KEYS nor ARGV

redis.eval("return 1")
  # => 1

@example EVAL with KEYS and ARGV as array arguments

redis.eval("return { KEYS, ARGV }", ["k1", "k2"], ["a1", "a2"])
  # => [["k1", "k2"], ["a1", "a2"]]

@example EVAL with KEYS and ARGV in a hash argument

redis.eval("return { KEYS, ARGV }", :keys => ["k1", "k2"], :argv => ["a1", "a2"])
  # => [["k1", "k2"], ["a1", "a2"]]

@param [Array<String>] keys optional array with keys to pass to the script @param [Array<String>] argv optional array with arguments to pass to the script @param [Hash] options

- `:keys => Array<String>`: optional array with keys to pass to the script
- `:argv => Array<String>`: optional array with arguments to pass to the script

@return depends on the script

@see script @see evalsha

# File lib/redis.rb, line 2302
def eval(*args)
  _eval(:eval, args)
end

Evaluate Lua script by its SHA.

@example EVALSHA without KEYS nor ARGV

redis.evalsha(sha)
  # => <depends on script>

@example EVALSHA with KEYS and ARGV as array arguments

redis.evalsha(sha, ["k1", "k2"], ["a1", "a2"])
  # => <depends on script>

@example EVALSHA with KEYS and ARGV in a hash argument

redis.evalsha(sha, :keys => ["k1", "k2"], :argv => ["a1", "a2"])
  # => <depends on script>

@param [Array<String>] keys optional array with keys to pass to the script @param [Array<String>] argv optional array with arguments to pass to the script @param [Hash] options

- `:keys => Array<String>`: optional array with keys to pass to the script
- `:argv => Array<String>`: optional array with arguments to pass to the script

@return depends on the script

@see script @see eval

# File lib/redis.rb, line 2327
def evalsha(*args)
  _eval(:evalsha, args)
end

Execute all commands issued after MULTI.

Only call this method when `#multi` was called *without* a block.

@return [nil, Array<…>]

- when commands were not executed, `nil`
- when commands were executed, an array with their replies

@see multi @see discard

# File lib/redis.rb, line 2200
def exec
  synchronize do |client|
    client.call([:exec])
  end
end

Determine if a key exists.

@param [String] key @return [Boolean]

# File lib/redis.rb, line 429
def exists(key)
  synchronize do |client|
    client.call([:exists, key], &_boolify)
  end
end

Set a key's time to live in seconds.

@param [String] key @param [Fixnum] seconds time to live @return [Boolean] whether the timeout was set or not

# File lib/redis.rb, line 312
def expire(key, seconds)
  synchronize do |client|
    client.call([:expire, key, seconds], &_boolify)
  end
end

Set the expiration for a key as a UNIX timestamp.

@param [String] key @param [Fixnum] unix_time expiry time specified as a UNIX timestamp @return [Boolean] whether the timeout was set or not

# File lib/redis.rb, line 323
def expireat(key, unix_time)
  synchronize do |client|
    client.call([:expireat, key, unix_time], &_boolify)
  end
end

Remove all keys from all databases.

@return [String] `OK`

# File lib/redis.rb, line 170
def flushall
  synchronize do |client|
    client.call([:flushall])
  end
end

Remove all keys from the current database.

@return [String] `OK`

# File lib/redis.rb, line 179
def flushdb
  synchronize do |client|
    client.call([:flushdb])
  end
end

Get the value of a key.

@param [String] key @return [String]

# File lib/redis.rb, line 787
def get(key)
  synchronize do |client|
    client.call([:get, key])
  end
end

Returns the bit value at offset in the string value stored at key.

@param [String] key @param [Fixnum] offset bit offset @return [Fixnum] `0` or `1`

# File lib/redis.rb, line 873
def getbit(key, offset)
  synchronize do |client|
    client.call([:getbit, key, offset])
  end
end

Get a substring of the string stored at a key.

@param [String] key @param [Fixnum] start zero-based start offset @param [Fixnum] stop zero-based end offset. Use -1 for representing

the end of the string

@return [Fixnum] `0` or `1`

# File lib/redis.rb, line 850
def getrange(key, start, stop)
  synchronize do |client|
    client.call([:getrange, key, start, stop])
  end
end

Set the string value of a key and return its old value.

@param [String] key @param [String] value value to replace the current value with @return [String] the old value stored in the key, or `nil` if the key

did not exist

# File lib/redis.rb, line 941
def getset(key, value)
  synchronize do |client|
    client.call([:getset, key, value.to_s])
  end
end

Delete one or more hash fields.

@param [String] key @param [String, Array<String>] field @return [Fixnum] the number of fields that were removed from the hash

# File lib/redis.rb, line 1948
def hdel(key, field)
  synchronize do |client|
    client.call([:hdel, key, field])
  end
end

Determine if a hash field exists.

@param [String] key @param [String] field @return [Boolean] whether or not the field exists in the hash

# File lib/redis.rb, line 1959
def hexists(key, field)
  synchronize do |client|
    client.call([:hexists, key, field], &_boolify)
  end
end

Get the value of a hash field.

@param [String] key @param [String] field @return [String]

# File lib/redis.rb, line 1899
def hget(key, field)
  synchronize do |client|
    client.call([:hget, key, field])
  end
end

Get all the fields and values in a hash.

@param [String] key @return [Hash<String, String>]

# File lib/redis.rb, line 2013
def hgetall(key)
  synchronize do |client|
    client.call([:hgetall, key], &_hashify)
  end
end

Increment the integer value of a hash field by the given integer number.

@param [String] key @param [String] field @param [Fixnum] increment @return [Fixnum] value of the field after incrementing it

# File lib/redis.rb, line 1971
def hincrby(key, field, increment)
  synchronize do |client|
    client.call([:hincrby, key, field, increment])
  end
end

Increment the numeric value of a hash field by the given float number.

@param [String] key @param [String] field @param [Float] increment @return [Float] value of the field after incrementing it

# File lib/redis.rb, line 1983
def hincrbyfloat(key, field, increment)
  synchronize do |client|
    client.call([:hincrbyfloat, key, field, increment], &_floatify)
  end
end

Get all the fields in a hash.

@param [String] key @return [Array<String>]

# File lib/redis.rb, line 1993
def hkeys(key)
  synchronize do |client|
    client.call([:hkeys, key])
  end
end

Get the number of fields in a hash.

@param [String] key @return [Fixnum] number of fields in the hash

# File lib/redis.rb, line 1832
def hlen(key)
  synchronize do |client|
    client.call([:hlen, key])
  end
end

Get the values of all the given hash fields.

@example

redis.hmget("hash", "f1", "f2")
  # => ["v1", "v2"]

@param [String] key @param [Array<String>] fields array of fields @return [Array<String>] an array of values for the specified fields

@see mapped_hmget

# File lib/redis.rb, line 1916
def hmget(key, *fields, &blk)
  synchronize do |client|
    client.call([:hmget, key] + fields, &blk)
  end
end

Set one or more hash values.

@example

redis.hmset("hash", "f1", "v1", "f2", "v2")
  # => "OK"

@param [String] key @param [Array<String>] attrs array of fields and values @return `“OK”`

@see mapped_hmset

# File lib/redis.rb, line 1873
def hmset(key, *attrs)
  synchronize do |client|
    client.call([:hmset, key] + attrs)
  end
end

Scan a hash

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

redis.hscan("hash", 0)

@param [String, Integer] cursor: the cursor of the iteration @param [Hash] options

- `:match => String`: only return keys matching the pattern
- `:count => Integer`: return count keys at most per iteration

@return [String, Array<[String, String]>] the next cursor and all found keys

# File lib/redis.rb, line 2404
def hscan(key, cursor, options={})
  _scan(:hscan, cursor, [key], options) do |reply|
    [reply[0], _pairify(reply[1])]
  end
end

Scan a hash

@example Retrieve all of the key/value pairs in a hash

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

@param [Hash] options

- `:match => String`: only return keys matching the pattern
- `:count => Integer`: return count keys at most per iteration

@return [Enumerator] an enumerator for all found keys

# File lib/redis.rb, line 2421
def hscan_each(key, options={}, &block)
  return to_enum(:hscan_each, key, options) unless block_given?
  cursor = 0
  loop do
    cursor, values = hscan(key, cursor, options)
    values.each(&block)
    break if cursor == "0"
  end
end

Set the string value of a hash field.

@param [String] key @param [String] field @param [String] value @return [Boolean] whether or not the field was *added* to the hash

# File lib/redis.rb, line 1844
def hset(key, field, value)
  synchronize do |client|
    client.call([:hset, key, field, value], &_boolify)
  end
end

Set the value of a hash field, only if the field does not exist.

@param [String] key @param [String] field @param [String] value @return [Boolean] whether or not the field was *added* to the hash

# File lib/redis.rb, line 1856
def hsetnx(key, field, value)
  synchronize do |client|
    client.call([:hsetnx, key, field, value], &_boolify)
  end
end

Get all the values in a hash.

@param [String] key @return [Array<String>]

# File lib/redis.rb, line 2003
def hvals(key)
  synchronize do |client|
    client.call([:hvals, key])
  end
end

Increment the integer value of a key by one.

@example

redis.incr("value")
  # => 6

@param [String] key @return [Fixnum] value after incrementing it

# File lib/redis.rb, line 616
def incr(key)
  synchronize do |client|
    client.call([:incr, key])
  end
end

Increment the integer value of a key by the given integer number.

@example

redis.incrby("value", 5)
  # => 10

@param [String] key @param [Fixnum] increment @return [Fixnum] value after incrementing it

# File lib/redis.rb, line 631
def incrby(key, increment)
  synchronize do |client|
    client.call([:incrby, key, increment])
  end
end

Increment the numeric value of a key by the given float number.

@example

redis.incrbyfloat("value", 1.23)
  # => 1.23

@param [String] key @param [Float] increment @return [Float] value after incrementing it

# File lib/redis.rb, line 646
def incrbyfloat(key, increment)
  synchronize do |client|
    client.call([:incrbyfloat, key, increment], &_floatify)
  end
end

Get information and statistics about the server.

@param [String, Symbol] cmd e.g. “commandstats” @return [Hash<String, String>]

# File lib/redis.rb, line 189
def info(cmd = nil)
  synchronize do |client|
    client.call([:info, cmd].compact) do |reply|
      if reply.kind_of?(String)
        reply = Hash[reply.split("\r\n").map do |line|
          line.split(":", 2) unless line =~ /^(#|$)/
        end.compact]

        if cmd && cmd.to_s == "commandstats"
          # Extract nested hashes for INFO COMMANDSTATS
          reply = Hash[reply.map do |k, v|
            v = v.split(",").map { |e| e.split("=") }
            [k[/^cmdstat_(.*)$/, 1], Hash[v]]
          end]
        end
      end

      reply
    end
  end
end

Find all keys matching the given pattern.

@param [String] pattern @return [Array<String>]

# File lib/redis.rb, line 439
def keys(pattern = "*")
  synchronize do |client|
    client.call([:keys, pattern]) do |reply|
      if reply.kind_of?(String)
        reply.split(" ")
      else
        reply
      end
    end
  end
end

Get the UNIX time stamp of the last successful save to disk.

@return [Fixnum]

# File lib/redis.rb, line 214
def lastsave
  synchronize do |client|
    client.call([:lastsave])
  end
end

Get an element from a list by its index.

@param [String] key @param [Fixnum] index @return [String]

# File lib/redis.rb, line 1141
def lindex(key, index)
  synchronize do |client|
    client.call([:lindex, key, index])
  end
end

Insert an element before or after another element in a list.

@param [String] key @param [String, Symbol] where `BEFORE` or `AFTER` @param [String] pivot reference element @param [String] value @return [Fixnum] length of the list after the insert operation, or `-1`

when the element `pivot` was not found

# File lib/redis.rb, line 1155
def linsert(key, where, pivot, value)
  synchronize do |client|
    client.call([:linsert, key, where, pivot, value])
  end
end

Get the length of a list.

@param [String] key @return [Fixnum]

# File lib/redis.rb, line 962
def llen(key)
  synchronize do |client|
    client.call([:llen, key])
  end
end

Remove and get the first element in a list.

@param [String] key @return [String]

# File lib/redis.rb, line 1016
def lpop(key)
  synchronize do |client|
    client.call([:lpop, key])
  end
end

Prepend one or more values to a list, creating the list if it doesn't exist

@param [String] key @param [String, Array] string value, or array of string values to push @return [Fixnum] the length of the list after the push operation

# File lib/redis.rb, line 973
def lpush(key, value)
  synchronize do |client|
    client.call([:lpush, key, value])
  end
end

Prepend a value to a list, only if the list exists.

@param [String] key @param [String] value @return [Fixnum] the length of the list after the push operation

# File lib/redis.rb, line 984
def lpushx(key, value)
  synchronize do |client|
    client.call([:lpushx, key, value])
  end
end

Get a range of elements from a list.

@param [String] key @param [Fixnum] start start index @param [Fixnum] stop stop index @return [Array<String>]

# File lib/redis.rb, line 1167
def lrange(key, start, stop)
  synchronize do |client|
    client.call([:lrange, key, start, stop])
  end
end

Remove elements from a list.

@param [String] key @param [Fixnum] count number of elements to remove. Use a positive

value to remove the first `count` occurrences of `value`. A negative
value to remove the last `count` occurrences of `value`. Or zero, to
remove all occurrences of `value` from the list.

@param [String] value @return [Fixnum] the number of removed elements

# File lib/redis.rb, line 1182
def lrem(key, count, value)
  synchronize do |client|
    client.call([:lrem, key, count, value])
  end
end

Set the value of an element in a list by its index.

@param [String] key @param [Fixnum] index @param [String] value @return [String] `OK`

# File lib/redis.rb, line 1194
def lset(key, index, value)
  synchronize do |client|
    client.call([:lset, key, index, value])
  end
end

Trim a list to the specified range.

@param [String] key @param [Fixnum] start start index @param [Fixnum] stop stop index @return [String] `OK`

# File lib/redis.rb, line 1206
def ltrim(key, start, stop)
  synchronize do |client|
    client.call([:ltrim, key, start, stop])
  end
end

Get the values of all the given hash fields.

@example

redis.mapped_hmget("hash", "f1", "f2")
  # => { "f1" => "v1", "f2" => "v2" }

@param [String] key @param [Array<String>] fields array of fields @return [Hash] a hash mapping the specified fields to their values

@see hmget

# File lib/redis.rb, line 1933
def mapped_hmget(key, *fields)
  hmget(key, *fields) do |reply|
    if reply.kind_of?(Array)
      Hash[fields.zip(reply)]
    else
      reply
    end
  end
end

Set one or more hash values.

@example

redis.mapped_hmset("hash", { "f1" => "v1", "f2" => "v2" })
  # => "OK"

@param [String] key @param [Hash] a non-empty hash with fields mapping to values @return `“OK”`

@see hmset

# File lib/redis.rb, line 1890
def mapped_hmset(key, hash)
  hmset(key, hash.to_a.flatten)
end

Get the values of all the given keys.

@example

redis.mapped_mget("key1", "key1")
  # => { "key1" => "v1", "key2" => "v2" }

@param [Array<String>] keys array of keys @return [Hash] a hash mapping the specified keys to their values

@see mget

# File lib/redis.rb, line 821
def mapped_mget(*keys)
  mget(*keys) do |reply|
    if reply.kind_of?(Array)
      Hash[keys.zip(reply)]
    else
      reply
    end
  end
end

Set one or more values.

@example

redis.mapped_mset({ "f1" => "v1", "f2" => "v2" })
  # => "OK"

@param [Hash] hash keys mapping to values @return `“OK”`

@see mset

# File lib/redis.rb, line 749
def mapped_mset(hash)
  mset(hash.to_a.flatten)
end

Set one or more values, only if none of the keys exist.

@example

redis.mapped_msetnx({ "key1" => "v1", "key2" => "v2" })
  # => true

@param [Hash] hash keys mapping to values @return [Boolean] whether or not all values were set

@see msetnx

# File lib/redis.rb, line 779
def mapped_msetnx(hash)
  msetnx(hash.to_a.flatten)
end

Get the values of all the given keys.

@example

redis.mget("key1", "key1")
  # => ["v1", "v2"]

@param [Array<String>] keys @return [Array<String>] an array of values for the specified keys

@see mapped_mget

# File lib/redis.rb, line 805
def mget(*keys, &blk)
  synchronize do |client|
    client.call([:mget] + keys, &blk)
  end
end

Transfer a key from the connected instance to another instance.

@param [String] key @param [Hash] options

- `:host => String`: host of instance to migrate to
- `:port => Integer`: port of instance to migrate to
- `:db => Integer`: database to migrate to (default: same as source)
- `:timeout => Integer`: timeout (default: same as connection timeout)

@return [String] `“OK”`

# File lib/redis.rb, line 404
def migrate(key, options)
  host = options[:host] || raise(RuntimeError, ":host not specified")
  port = options[:port] || raise(RuntimeError, ":port not specified")
  db = (options[:db] || client.db).to_i
  timeout = (options[:timeout] || client.timeout).to_i

  synchronize do |client|
    client.call([:migrate, host, port, key, db, timeout])
  end
end

Listen for all requests received by the server in real time.

There is no way to interrupt this command.

@yield a block to be called for every line of output @yieldparam [String] line timestamp and command that was executed

# File lib/redis.rb, line 226
def monitor(&block)
  synchronize do |client|
    client.call_loop([:monitor], &block)
  end
end

Move a key to another database.

@example Move a key to another database

redis.set "foo", "bar"
  # => "OK"
redis.move "foo", 2
  # => true
redis.exists "foo"
  # => false
redis.select 2
  # => "OK"
redis.exists "foo"
  # => true
redis.get "foo"
  # => "bar"

@param [String] key @param [Fixnum] db @return [Boolean] whether the key was moved or not

# File lib/redis.rb, line 470
def move(key, db)
  synchronize do |client|
    client.call([:move, key, db], &_boolify)
  end
end

Set one or more values.

@example

redis.mset("key1", "v1", "key2", "v2")
  # => "OK"

@param [Array<String>] args array of keys and values @return `“OK”`

@see mapped_mset

# File lib/redis.rb, line 733
def mset(*args)
  synchronize do |client|
    client.call([:mset] + args)
  end
end

Set one or more values, only if none of the keys exist.

@example

redis.msetnx("key1", "v1", "key2", "v2")
  # => true

@param [Array<String>] args array of keys and values @return [Boolean] whether or not all values were set

@see mapped_msetnx

# File lib/redis.rb, line 763
def msetnx(*args)
  synchronize do |client|
    client.call([:msetnx] + args, &_boolify)
  end
end

Mark the start of a transaction block.

Passing a block is optional.

@example With a block

redis.multi do |multi|
  multi.set("key", "value")
  multi.incr("counter")
end # => ["OK", 6]

@example Without a block

redis.multi
  # => "OK"
redis.set("key", "value")
  # => "QUEUED"
redis.incr("counter")
  # => "QUEUED"
redis.exec
  # => ["OK", 6]

@yield [multi] the commands that are called inside this block are cached

and written to the server upon returning from it

@yieldparam [Redis] multi `self`

@return [String, Array<…>]

- when a block is not given, `OK`
- when a block is given, an array with replies

@see watch @see unwatch

# File lib/redis.rb, line 2173
def multi
  synchronize do |client|
    if !block_given?
      client.call([:multi])
    else
      begin
        pipeline = Pipeline::Multi.new
        original, @client = @client, pipeline
        yield(self)
        original.call_pipeline(pipeline)
      ensure
        @client = original
      end
    end
  end
end

Remove the expiration from a key.

@param [String] key @return [Boolean] whether the timeout was removed or not

# File lib/redis.rb, line 301
def persist(key)
  synchronize do |client|
    client.call([:persist, key], &_boolify)
  end
end

Set a key's time to live in milliseconds.

@param [String] key @param [Fixnum] milliseconds time to live @return [Boolean] whether the timeout was set or not

# File lib/redis.rb, line 345
def pexpire(key, milliseconds)
  synchronize do |client|
    client.call([:pexpire, key, milliseconds], &_boolify)
  end
end

Set the expiration for a key as number of milliseconds from UNIX Epoch.

@param [String] key @param [Fixnum] ms_unix_time expiry time specified as number of milliseconds from UNIX Epoch. @return [Boolean] whether the timeout was set or not

# File lib/redis.rb, line 356
def pexpireat(key, ms_unix_time)
  synchronize do |client|
    client.call([:pexpireat, key, ms_unix_time], &_boolify)
  end
end

Add one or more members to a HyperLogLog structure.

@param [String] key @param [String, Array<String>] member one member, or array of members @return [Boolean] true if at least 1 HyperLogLog internal register was altered. false otherwise.

# File lib/redis.rb, line 2511
def pfadd(key, member)
  synchronize do |client|
    client.call([:pfadd, key, member], &_boolify)
  end
end

Get the approximate cardinality of members added to HyperLogLog structure.

If called with multiple keys, returns the approximate cardinality of the union of the HyperLogLogs contained in the keys.

@param [String, Array<String>] keys @return [Fixnum]

# File lib/redis.rb, line 2524
def pfcount(*keys)
  synchronize do |client|
    client.call([:pfcount] + keys)
  end
end

Merge multiple HyperLogLog values into an unique value that will approximate the cardinality of the union of the observed Sets of the source HyperLogLog structures.

@param [String] dest_key destination key @param [String, Array<String>] source_key source key, or array of keys @return [Boolean]

# File lib/redis.rb, line 2536
def pfmerge(dest_key, *source_key)
  synchronize do |client|
    client.call([:pfmerge, dest_key, *source_key], &_boolify_set)
  end
end

Ping the server.

@return [String] `PONG`

# File lib/redis.rb, line 87
def ping
  synchronize do |client|
    client.call([:ping])
  end
end

Set the time to live in milliseconds of a key.

@param [String] key @param [Fixnum] ttl @param [String] value @return `“OK”`

# File lib/redis.rb, line 706
def psetex(key, ttl, value)
  synchronize do |client|
    client.call([:psetex, key, ttl, value.to_s])
  end
end

Listen for messages published to channels matching the given patterns.

# File lib/redis.rb, line 2048
def psubscribe(*channels, &block)
  synchronize do |client|
    _subscription(:psubscribe, channels, block)
  end
end

Get the time to live (in milliseconds) for a key.

@param [String] key @return [Fixnum] remaining time to live in milliseconds, or -1 if the

key does not exist or does not have a timeout

# File lib/redis.rb, line 367
def pttl(key)
  synchronize do |client|
    client.call([:pttl, key])
  end
end

Post a message to a channel.

# File lib/redis.rb, line 2020
def publish(channel, message)
  synchronize do |client|
    client.call([:publish, channel, message])
  end
end

Inspect the state of the Pub/Sub subsystem. Possible subcommands: channels, numsub, numpat.

# File lib/redis.rb, line 2064
def pubsub(subcommand, *args)
  synchronize do |client|
    client.call([:pubsub, subcommand] + args)
  end
end

Stop listening for messages posted to channels matching the given patterns.

# File lib/redis.rb, line 2055
def punsubscribe(*channels)
  synchronize do |client|
    raise RuntimeError, "Can't unsubscribe if not subscribed." unless subscribed?
    client.punsubscribe(*channels)
  end
end

Close the connection.

@return [String] `OK`

# File lib/redis.rb, line 106
def quit
  synchronize do |client|
    begin
      client.call([:quit])
    rescue ConnectionError
    ensure
      client.disconnect
    end
  end
end

Return a random key from the keyspace.

@return [String]

# File lib/redis.rb, line 485
def randomkey
  synchronize do |client|
    client.call([:randomkey])
  end
end

Rename a key. If the new key already exists it is overwritten.

@param [String] old_name @param [String] new_name @return [String] `OK`

# File lib/redis.rb, line 496
def rename(old_name, new_name)
  synchronize do |client|
    client.call([:rename, old_name, new_name])
  end
end

Rename a key, only if the new key does not exist.

@param [String] old_name @param [String] new_name @return [Boolean] whether the key was renamed or not

# File lib/redis.rb, line 507
def renamenx(old_name, new_name)
  synchronize do |client|
    client.call([:renamenx, old_name, new_name], &_boolify)
  end
end

Create a key using the serialized value, previously obtained using DUMP.

@param [String] key @param [String] ttl @param [String] serialized_value @return `“OK”`

# File lib/redis.rb, line 389
def restore(key, ttl, serialized_value)
  synchronize do |client|
    client.call([:restore, key, ttl, serialized_value])
  end
end

Remove and get the last element in a list.

@param [String] key @return [String]

# File lib/redis.rb, line 1026
def rpop(key)
  synchronize do |client|
    client.call([:rpop, key])
  end
end

Remove the last element in a list, append it to another list and return it.

@param [String] source source key @param [String] destination destination key @return [nil, String] the element, or nil when the source key does not exist

# File lib/redis.rb, line 1037
def rpoplpush(source, destination)
  synchronize do |client|
    client.call([:rpoplpush, source, destination])
  end
end

Append one or more values to a list, creating the list if it doesn't exist

@param [String] key @param [String] value @return [Fixnum] the length of the list after the push operation

# File lib/redis.rb, line 995
def rpush(key, value)
  synchronize do |client|
    client.call([:rpush, key, value])
  end
end

Append a value to a list, only if the list exists.

@param [String] key @param [String] value @return [Fixnum] the length of the list after the push operation

# File lib/redis.rb, line 1006
def rpushx(key, value)
  synchronize do |client|
    client.call([:rpushx, key, value])
  end
end

Add one or more members to a set.

@param [String] key @param [String, Array<String>] member one member, or array of members @return [Boolean, Fixnum] `Boolean` when a single member is specified,

holding whether or not adding the member succeeded, or `Fixnum` when an
array of members is specified, holding the number of members that were
successfully added

# File lib/redis.rb, line 1230
def sadd(key, member)
  synchronize do |client|
    client.call([:sadd, key, member]) do |reply|
      if member.is_a? Array
        # Variadic: return integer
        reply
      else
        # Single argument: return boolean
        _boolify.call(reply)
      end
    end
  end
end

Synchronously save the dataset to disk.

@return [String]

# File lib/redis.rb, line 235
def save
  synchronize do |client|
    client.call([:save])
  end
end

Scan the keyspace

@example Retrieve the first batch of keys

redis.scan(0)
  # => ["4", ["key:21", "key:47", "key:42"]]

@example Retrieve a batch of keys matching a pattern

redis.scan(4, :match => "key:1?")
  # => ["92", ["key:13", "key:18"]]

@param [String, Integer] cursor: the cursor of the iteration @param [Hash] options

- `:match => String`: only return keys matching the pattern
- `:count => Integer`: return count keys at most per iteration

@return [String, Array<String>] the next cursor and all found keys

# File lib/redis.rb, line 2364
def scan(cursor, options={})
  _scan(:scan, cursor, [], options)
end

Scan the keyspace

@example Retrieve all of the keys (with possible duplicates)

redis.scan_each.to_a
  # => ["key:21", "key:47", "key:42"]

@example Execute block for each key matching a pattern

redis.scan_each(:match => "key:1?") {|key| puts key}
  # => key:13
  # => key:18

@param [Hash] options

- `:match => String`: only return keys matching the pattern
- `:count => Integer`: return count keys at most per iteration

@return [Enumerator] an enumerator for all found keys

# File lib/redis.rb, line 2383
def scan_each(options={}, &block)
  return to_enum(:scan_each, options) unless block_given?
  cursor = 0
  loop do
    cursor, keys = scan(cursor, options)
    keys.each(&block)
    break if cursor == "0"
  end
end

Get the number of members in a set.

@param [String] key @return [Fixnum]

# File lib/redis.rb, line 1216
def scard(key)
  synchronize do |client|
    client.call([:scard, key])
  end
end

Control remote script registry.

@example Load a script

sha = redis.script(:load, "return 1")
  # => <sha of this script>

@example Check if a script exists

redis.script(:exists, sha)
  # => true

@example Check if multiple scripts exist

redis.script(:exists, [sha, other_sha])
  # => [true, false]

@example Flush the script registry

redis.script(:flush)
  # => "OK"

@example Kill a running script

redis.script(:kill)
  # => "OK"

@param [String] subcommand e.g. `exists`, `flush`, `load`, `kill` @param [Array<String>] args depends on subcommand @return [String, Boolean, Array<Boolean>, …] depends on subcommand

@see eval @see evalsha

# File lib/redis.rb, line 2244
def script(subcommand, *args)
  subcommand = subcommand.to_s.downcase

  if subcommand == "exists"
    synchronize do |client|
      arg = args.first

      client.call([:script, :exists, arg]) do |reply|
        reply = reply.map { |r| _boolify.call(r) }

        if arg.is_a?(Array)
          reply
        else
          reply.first
        end
      end
    end
  else
    synchronize do |client|
      client.call([:script, subcommand] + args)
    end
  end
end

Subtract multiple sets.

@param [String, Array<String>] keys keys pointing to sets to subtract @return [Array<String>] members in the difference

# File lib/redis.rb, line 1328
def sdiff(*keys)
  synchronize do |client|
    client.call([:sdiff] + keys)
  end
end

Subtract multiple sets and store the resulting set in a key.

@param [String] destination destination key @param [String, Array<String>] keys keys pointing to sets to subtract @return [Fixnum] number of elements in the resulting set

# File lib/redis.rb, line 1339
def sdiffstore(destination, *keys)
  synchronize do |client|
    client.call([:sdiffstore, destination] + keys)
  end
end

Change the selected database for the current connection.

@param [Fixnum] db zero-based index of the DB to use (0 to 15) @return [String] `OK`

# File lib/redis.rb, line 77
def select(db)
  synchronize do |client|
    client.db = db
    client.call([:select, db])
  end
end

Set the string value of a key.

@param [String] key @param [String] value @param [Hash] options

- `:ex => Fixnum`: Set the specified expire time, in seconds.
- `:px => Fixnum`: Set the specified expire time, in milliseconds.
- `:nx => true`: Only set the key if it does not already exist.
- `:xx => true`: Only set the key if it already exist.

@return [String, Boolean] `“OK”` or true, false if `:nx => true` or `:xx => true`

# File lib/redis.rb, line 662
def set(key, value, options = {})
  args = []

  ex = options[:ex]
  args.concat(["EX", ex]) if ex

  px = options[:px]
  args.concat(["PX", px]) if px

  nx = options[:nx]
  args.concat(["NX"]) if nx

  xx = options[:xx]
  args.concat(["XX"]) if xx

  synchronize do |client|
    if nx || xx
      client.call([:set, key, value.to_s] + args, &_boolify_set)
    else
      client.call([:set, key, value.to_s] + args)
    end
  end
end

Sets or clears the bit at offset in the string value stored at key.

@param [String] key @param [Fixnum] offset bit offset @param [Fixnum] value bit value `0` or `1` @return [Fixnum] the original bit value stored at `offset`

# File lib/redis.rb, line 862
def setbit(key, offset, value)
  synchronize do |client|
    client.call([:setbit, key, offset, value])
  end
end

Set the time to live in seconds of a key.

@param [String] key @param [Fixnum] ttl @param [String] value @return `“OK”`

# File lib/redis.rb, line 694
def setex(key, ttl, value)
  synchronize do |client|
    client.call([:setex, key, ttl, value.to_s])
  end
end

Set the value of a key, only if the key does not exist.

@param [String] key @param [String] value @return [Boolean] whether the key was set or not

# File lib/redis.rb, line 717
def setnx(key, value)
  synchronize do |client|
    client.call([:setnx, key, value.to_s], &_boolify)
  end
end

Overwrite part of a string at key starting at the specified offset.

@param [String] key @param [Fixnum] offset byte offset @param [String] value @return [Fixnum] length of the string after it was modified

# File lib/redis.rb, line 837
def setrange(key, offset, value)
  synchronize do |client|
    client.call([:setrange, key, offset, value.to_s])
  end
end

Synchronously save the dataset to disk and then shut down the server.

# File lib/redis.rb, line 242
def shutdown
  synchronize do |client|
    client.with_reconnect(false) do
      begin
        client.call([:shutdown])
      rescue ConnectionError
        # This means Redis has probably exited.
        nil
      end
    end
  end
end

Intersect multiple sets.

@param [String, Array<String>] keys keys pointing to sets to intersect @return [Array<String>] members in the intersection

# File lib/redis.rb, line 1349
def sinter(*keys)
  synchronize do |client|
    client.call([:sinter] + keys)
  end
end

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

@param [String] destination destination key @param [String, Array<String>] keys keys pointing to sets to intersect @return [Fixnum] number of elements in the resulting set

# File lib/redis.rb, line 1360
def sinterstore(destination, *keys)
  synchronize do |client|
    client.call([:sinterstore, destination] + keys)
  end
end

Determine if a given value is a member of a set.

@param [String] key @param [String] member @return [Boolean]

# File lib/redis.rb, line 1308
def sismember(key, member)
  synchronize do |client|
    client.call([:sismember, key, member], &_boolify)
  end
end

Make the server a slave of another instance, or promote it as master.

# File lib/redis.rb, line 256
def slaveof(host, port)
  synchronize do |client|
    client.call([:slaveof, host, port])
  end
end

Interact with the slowlog (get, len, reset)

@param [String] subcommand e.g. `get`, `len`, `reset` @param [Fixnum] length maximum number of entries to return @return [Array<String>, Fixnum, String] depends on subcommand

# File lib/redis.rb, line 267
def slowlog(subcommand, length=nil)
  synchronize do |client|
    args = [:slowlog, subcommand]
    args << length if length
    client.call args
  end
end

Get all the members in a set.

@param [String] key @return [Array<String>]

# File lib/redis.rb, line 1318
def smembers(key)
  synchronize do |client|
    client.call([:smembers, key])
  end
end

Move a member from one set to another.

@param [String] source source key @param [String] destination destination key @param [String] member member to move from `source` to `destination` @return [Boolean]

# File lib/redis.rb, line 1297
def smove(source, destination, member)
  synchronize do |client|
    client.call([:smove, source, destination, member], &_boolify)
  end
end

Sort the elements in a list, set or sorted set.

@example Retrieve the first 2 elements from an alphabetically sorted “list”

redis.sort("list", :order => "alpha", :limit => [0, 2])
  # => ["a", "b"]

@example Store an alphabetically descending list in “target”

redis.sort("list", :order => "desc alpha", :store => "target")
  # => 26

@param [String] key @param [Hash] options

- `:by => String`: use external key to sort elements by
- `:limit => [offset, count]`: skip `offset` elements, return a maximum
of `count` elements
- `:get => [String, Array<String>]`: single key or array of keys to
retrieve per element in the result
- `:order => String`: combination of `ASC`, `DESC` and optionally `ALPHA`
- `:store => String`: key to store the result at

@return [Array<String>, Array<Array<String>>, Fixnum]

- when `:get` is not specified, or holds a single element, an array of elements
- when `:get` is specified, and holds more than one element, an array of
elements where every element is an array with the result for every
element specified in `:get`
- when `:store` is specified, the number of elements in the stored result

# File lib/redis.rb, line 538
def sort(key, options = {})
  args = []

  by = options[:by]
  args.concat(["BY", by]) if by

  limit = options[:limit]
  args.concat(["LIMIT"] + limit) if limit

  get = Array(options[:get])
  args.concat(["GET"].product(get).flatten) unless get.empty?

  order = options[:order]
  args.concat(order.split(" ")) if order

  store = options[:store]
  args.concat(["STORE", store]) if store

  synchronize do |client|
    client.call([:sort, key] + args) do |reply|
      if get.size > 1 && !store
        if reply
          reply.each_slice(get.size).to_a
        end
      else
        reply
      end
    end
  end
end

Remove and return a random member from a set.

@param [String] key @return [String]

# File lib/redis.rb, line 1270
def spop(key)
  synchronize do |client|
    client.call([:spop, key])
  end
end

Get one or more random members from a set.

@param [String] key @param [Fixnum] count @return [String]

# File lib/redis.rb, line 1281
def srandmember(key, count = nil)
  synchronize do |client|
    if count.nil?
      client.call([:srandmember, key])
    else
      client.call([:srandmember, key, count])
    end
  end
end

Remove one or more members from a set.

@param [String] key @param [String, Array<String>] member one member, or array of members @return [Boolean, Fixnum] `Boolean` when a single member is specified,

holding whether or not removing the member succeeded, or `Fixnum` when an
array of members is specified, holding the number of members that were
successfully removed

# File lib/redis.rb, line 1252
def srem(key, member)
  synchronize do |client|
    client.call([:srem, key, member]) do |reply|
      if member.is_a? Array
        # Variadic: return integer
        reply
      else
        # Single argument: return boolean
        _boolify.call(reply)
      end
    end
  end
end

Scan a set

@example Retrieve the first batch of keys in a set

redis.sscan("set", 0)

@param [String, Integer] cursor: the cursor of the iteration @param [Hash] options

- `:match => String`: only return keys matching the pattern
- `:count => Integer`: return count keys at most per iteration

@return [String, Array<String>] the next cursor and all found members

# File lib/redis.rb, line 2481
def sscan(key, cursor, options={})
  _scan(:sscan, cursor, [key], options)
end

Scan a set

@example Retrieve all of the keys in a set

redis.sscan_each("set").to_a
# => ["key1", "key2", "key3"]

@param [Hash] options

- `:match => String`: only return keys matching the pattern
- `:count => Integer`: return count keys at most per iteration

@return [Enumerator] an enumerator for all keys in the set

# File lib/redis.rb, line 2496
def sscan_each(key, options={}, &block)
  return to_enum(:sscan_each, key, options) unless block_given?
  cursor = 0
  loop do
    cursor, keys = sscan(key, cursor, options)
    keys.each(&block)
    break if cursor == "0"
  end
end

Get the length of the value stored in a key.

@param [String] key @return [Fixnum] the length of the value stored in the key, or 0

if the key does not exist

# File lib/redis.rb, line 952
def strlen(key)
  synchronize do |client|
    client.call([:strlen, key])
  end
end

Listen for messages published to the given channels.

# File lib/redis.rb, line 2033
def subscribe(*channels, &block)
  synchronize do |client|
    _subscription(:subscribe, channels, block)
  end
end

Add multiple sets.

@param [String, Array<String>] keys keys pointing to sets to unify @return [Array<String>] members in the union

# File lib/redis.rb, line 1370
def sunion(*keys)
  synchronize do |client|
    client.call([:sunion] + keys)
  end
end

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

@param [String] destination destination key @param [String, Array<String>] keys keys pointing to sets to unify @return [Fixnum] number of elements in the resulting set

# File lib/redis.rb, line 1381
def sunionstore(destination, *keys)
  synchronize do |client|
    client.call([:sunionstore, destination] + keys)
  end
end

Internal command used for replication.

# File lib/redis.rb, line 276
def sync
  synchronize do |client|
    client.call([:sync])
  end
end

Return the server time.

@example

r.time # => [ 1333093196, 606806 ]

@return [Array<Fixnum>] tuple of seconds since UNIX epoch and

microseconds in the current second

# File lib/redis.rb, line 289
def time
  synchronize do |client|
    client.call([:time]) do |reply|
      reply.map(&:to_i) if reply
    end
  end
end

Get the time to live (in seconds) for a key.

@param [String] key @return [Fixnum] remaining time to live in seconds, or -1 if the

key does not exist or does not have a timeout

# File lib/redis.rb, line 334
def ttl(key)
  synchronize do |client|
    client.call([:ttl, key])
  end
end

Determine the type stored at key.

@param [String] key @return [String] `string`, `list`, `set`, `zset`, `hash` or `none`

# File lib/redis.rb, line 573
def type(key)
  synchronize do |client|
    client.call([:type, key])
  end
end

Stop listening for messages posted to the given channels.

# File lib/redis.rb, line 2040
def unsubscribe(*channels)
  synchronize do |client|
    raise RuntimeError, "Can't unsubscribe if not subscribed." unless subscribed?
    client.unsubscribe(*channels)
  end
end

Forget about all watched keys.

@return [String] `OK`

@see watch @see multi

# File lib/redis.rb, line 2125
def unwatch
  synchronize do |client|
    client.call([:unwatch])
  end
end

Watch the given keys to determine execution of the MULTI/EXEC block.

Using a block is optional, but is necessary for thread-safety.

An `#unwatch` is automatically issued if an exception is raised within the block that is a subclass of StandardError and is not a ConnectionError.

@example With a block

redis.watch("key") do
  if redis.get("key") == "some value"
    redis.multi do |multi|
      multi.set("key", "other value")
      multi.incr("counter")
    end
  else
    redis.unwatch
  end
end
  # => ["OK", 6]

@example Without a block

redis.watch("key")
  # => "OK"

@param [String, Array<String>] keys one or more keys to watch @return [Object] if using a block, returns the return value of the block @return [String] if not using a block, returns `OK`

@see unwatch @see multi

# File lib/redis.rb, line 2100
def watch(*keys)
  synchronize do |client|
    res = client.call([:watch] + keys)

    if block_given?
      begin
        yield(self)
      rescue ConnectionError
        raise
      rescue StandardError
        unwatch
        raise
      end
    else
      res
    end
  end
end

Run code with the client reconnecting

# File lib/redis.rb, line 41
def with_reconnect(val=true, &blk)
  synchronize do |client|
    client.with_reconnect(val, &blk)
  end
end

Run code without the client reconnecting

# File lib/redis.rb, line 48
def without_reconnect(&blk)
  with_reconnect(false, &blk)
end

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

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

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

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

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

@param [String] key @param [[Float, String], Array<[Float, String]>] args

- a single `[score, member]` pair
- an array of `[score, member]` pairs

@return [Boolean, Fixnum]

- `Boolean` when a single pair is specified, holding whether or not it was
**added** to the sorted set
- `Fixnum` when an array of pairs is specified, holding the number of
pairs that were **added** to the sorted set

# File lib/redis.rb, line 1419
def zadd(key, *args)
  synchronize do |client|
    if args.size == 1 && args[0].is_a?(Array)
      # Variadic: return integer
      client.call([:zadd, key] + args[0])
    elsif args.size == 2
      # Single pair: return boolean
      client.call([:zadd, key, args[0], args[1]], &_boolify)
    else
      raise ArgumentError, "wrong number of arguments"
    end
  end
end

Get the number of members in a sorted set.

@example

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

@param [String] key @return [Fixnum]

# File lib/redis.rb, line 1395
def zcard(key)
  synchronize do |client|
    client.call([:zcard, key])
  end
end

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

@example Count members with score `>= 5` and `< 100`

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

@example Count members with scores `> 5`

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

@param [String] key @param [String] min

- inclusive minimum score is specified verbatim
- exclusive minimum score is specified by prefixing `(`

@param [String] max

- inclusive maximum score is specified verbatim
- exclusive maximum score is specified by prefixing `(`

@return [Fixnum] number of members in within the specified range

# File lib/redis.rb, line 1767
def zcount(key, min, max)
  synchronize do |client|
    client.call([:zcount, key, min, max])
  end
end

Increment the score of a member in a sorted set.

@example

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

@param [String] key @param [Float] increment @param [String] member @return [Float] score of the member after incrementing it

# File lib/redis.rb, line 1443
def zincrby(key, increment, member)
  synchronize do |client|
    client.call([:zincrby, key, increment, member], &_floatify)
  end
end

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

@example 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

@param [String] destination destination key @param [Array<String>] keys source keys @param [Hash] options

- `:weights => [Float, Float, ...]`: weights to associate with source
sorted sets
- `:aggregate => String`: aggregate function to use (sum, min, max, ...)

@return [Fixnum] number of elements in the resulting sorted set

# File lib/redis.rb, line 1787
def zinterstore(destination, keys, options = {})
  args = []

  weights = options[:weights]
  args.concat(["WEIGHTS"] + weights) if weights

  aggregate = options[:aggregate]
  args.concat(["AGGREGATE", aggregate]) if aggregate

  synchronize do |client|
    client.call([:zinterstore, destination, keys.size] + keys + args)
  end
end

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

@example Retrieve all members from a sorted set

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

@example Retrieve all members and their scores from a sorted set

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

@param [String] key @param [Fixnum] start start index @param [Fixnum] stop stop index @param [Hash] options

- `:with_scores => true`: include scores in output

@return [Array<String>, Array<[String, Float]>]

- when `:with_scores` is not specified, an array of members
- when `:with_scores` is specified, an array with `[member, score]` pairs

# File lib/redis.rb, line 1513
def zrange(key, start, stop, options = {})
  args = []

  with_scores = options[:with_scores] || options[:withscores]

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

  synchronize do |client|
    client.call([:zrange, key, start, stop] + args, &block)
  end
end

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

@example Retrieve members matching a

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

@example Retrieve the first 2 members matching a

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

@param [String] key @param [String] min

- inclusive minimum is specified by prefixing `(`
- exclusive minimum is specified by prefixing `[`

@param [String] max

- inclusive maximum is specified by prefixing `(`
- exclusive maximum is specified by prefixing `[`

@param [Hash] options

- `:limit => [offset, count]`: skip `offset` members, return a maximum of
`count` members

@return [Array<String>, Array<[String, Float]>]

# File lib/redis.rb, line 1617
def zrangebylex(key, min, max, options = {})
  args = []

  limit = options[:limit]
  args.concat(["LIMIT"] + limit) if limit

  synchronize do |client|
    client.call([:zrangebylex, key, min, max] + args)
  end
end

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

@example Retrieve members with score `>= 5` and `< 100`

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

@example Retrieve the first 2 members with score `>= 0`

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

@example Retrieve members and their scores with scores `> 5`

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

@param [String] key @param [String] min

- inclusive minimum score is specified verbatim
- exclusive minimum score is specified by prefixing `(`

@param [String] max

- inclusive maximum score is specified verbatim
- exclusive maximum score is specified by prefixing `(`

@param [Hash] options

- `:with_scores => true`: include scores in output
- `:limit => [offset, count]`: skip `offset` members, return a maximum of
`count` members

@return [Array<String>, Array<[String, Float]>]

- when `:with_scores` is not specified, an array of members
- when `:with_scores` is specified, an array with `[member, score]` pairs

# File lib/redis.rb, line 1677
def zrangebyscore(key, min, max, options = {})
  args = []

  with_scores = options[:with_scores] || options[:withscores]

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

  limit = options[:limit]
  args.concat(["LIMIT"] + limit) if limit

  synchronize do |client|
    client.call([:zrangebyscore, key, min, max] + args, &block)
  end
end

Determine the index of a member in a sorted set.

@param [String] key @param [String] member @return [Fixnum]

# File lib/redis.rb, line 1559
def zrank(key, member)
  synchronize do |client|
    client.call([:zrank, key, member])
  end
end

Remove one or more members from a sorted set.

@example Remove a single member from a sorted set

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

@example Remove an array of members from a sorted set

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

@param [String] key @param [String, Array<String>] member

- a single member
- an array of members

@return [Boolean, Fixnum]

- `Boolean` when a single member is specified, holding whether or not it
was removed from the sorted set
- `Fixnum` when an array of pairs is specified, holding the number of
members that were removed to the sorted set

# File lib/redis.rb, line 1466
def zrem(key, member)
  synchronize do |client|
    client.call([: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
end

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

@example Remove first 5 members

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

@example Remove last 5 members

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

@param [String] key @param [Fixnum] start start index @param [Fixnum] stop stop index @return [Fixnum] number of members that were removed

# File lib/redis.rb, line 1590
def zremrangebyrank(key, start, stop)
  synchronize do |client|
    client.call([:zremrangebyrank, key, start, stop])
  end
end

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

@example Remove members with score `>= 5` and `< 100`

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

@example Remove members with scores `> 5`

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

@param [String] key @param [String] min

- inclusive minimum score is specified verbatim
- exclusive minimum score is specified by prefixing `(`

@param [String] max

- inclusive maximum score is specified verbatim
- exclusive maximum score is specified by prefixing `(`

@return [Fixnum] number of members that were removed

# File lib/redis.rb, line 1744
def zremrangebyscore(key, min, max)
  synchronize do |client|
    client.call([:zremrangebyscore, key, min, max])
  end
end

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

@example Retrieve all members from a sorted set

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

@example 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 zrange

# File lib/redis.rb, line 1539
def zrevrange(key, start, stop, options = {})
  args = []

  with_scores = options[:with_scores] || options[:withscores]

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

  synchronize do |client|
    client.call([:zrevrange, key, start, stop] + args, &block)
  end
end

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.

@example Retrieve members matching a

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

@example Retrieve the last 2 members matching a

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

@see zrangebylex

# File lib/redis.rb, line 1639
def zrevrangebylex(key, max, min, options = {})
  args = []

  limit = options[:limit]
  args.concat(["LIMIT"] + limit) if limit

  synchronize do |client|
    client.call([:zrevrangebylex, key, max, min] + args)
  end
end

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

@example Retrieve members with score `< 100` and `>= 5`

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

@example Retrieve the first 2 members with score `<= 0`

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

@example Retrieve members and their scores with scores `> 5`

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

@see zrangebyscore

# File lib/redis.rb, line 1709
def zrevrangebyscore(key, max, min, options = {})
  args = []

  with_scores = options[:with_scores] || options[:withscores]

  if with_scores
    args << ["WITHSCORES"]
    block = _floatify_pairs
  end

  limit = options[:limit]
  args.concat(["LIMIT"] + limit) if limit

  synchronize do |client|
    client.call([:zrevrangebyscore, key, max, min] + args, &block)
  end
end

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

@param [String] key @param [String] member @return [Fixnum]

# File lib/redis.rb, line 1571
def zrevrank(key, member)
  synchronize do |client|
    client.call([:zrevrank, key, member])
  end
end

Scan a sorted set

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

redis.zscan("zset", 0)

@param [String, Integer] cursor: the cursor of the iteration @param [Hash] options

- `:match => String`: only return keys matching the pattern
- `:count => Integer`: return count keys at most per iteration

@return [String, Array<[String, Float]>] the next cursor and all found

members and scores

# File lib/redis.rb, line 2443
def zscan(key, cursor, options={})
  _scan(:zscan, cursor, [key], options) do |reply|
    [reply[0], _floatify_pairs.call(reply[1])]
  end
end

Scan a sorted set

@example Retrieve all of the members/scores in a sorted set

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

@param [Hash] options

- `:match => String`: only return keys matching the pattern
- `:count => Integer`: return count keys at most per iteration

@return [Enumerator] an enumerator for all found scores and members

# File lib/redis.rb, line 2460
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

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

@example Get the score for member “a”

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

@param [String] key @param [String] member @return [Float] score of the member

# File lib/redis.rb, line 1489
def zscore(key, member)
  synchronize do |client|
    client.call([:zscore, key, member], &_floatify)
  end
end

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

@example 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

@param [String] destination destination key @param [Array<String>] keys source keys @param [Hash] options

- `:weights => [Float, Float, ...]`: weights to associate with source
sorted sets
- `:aggregate => String`: aggregate function to use (sum, min, max, ...)

@return [Fixnum] number of elements in the resulting sorted set

# File lib/redis.rb, line 1814
def zunionstore(destination, keys, options = {})
  args = []

  weights = options[:weights]
  args.concat(["WEIGHTS"] + weights) if weights

  aggregate = options[:aggregate]
  args.concat(["AGGREGATE", aggregate]) if aggregate

  synchronize do |client|
    client.call([:zunionstore, destination, keys.size] + keys + args)
  end
end

Commands returning 1 for true and 0 for false may be executed in a pipeline where the method call will return nil. Propagate the nil instead of falsely returning false.

# File lib/redis.rb, line 2565
def _boolify
  lambda { |value|
    value == 1 if value
  }
end