Class: Redis

Inherits:
Object
  • Object
show all
Includes:
MonitorMixin
Defined in:
lib/redis.rb,
lib/redis/client.rb,
lib/redis/errors.rb,
lib/redis/version.rb,
lib/redis/pipeline.rb,
lib/redis/hash_ring.rb,
lib/redis/subscribe.rb,
lib/redis/distributed.rb

Defined Under Namespace

Classes: BaseConnectionError, BaseError, BasicObject, CannotConnectError, Client, CommandError, ConnectionError, Distributed, Future, FutureNotReady, HashRing, InheritedError, Pipeline, ProtocolError, SubscribedClient, Subscription, TimeoutError

Constant Summary collapse

VERSION = 
"3.0.6"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Redis

Returns a new instance of Redis.



29
30
31
32
33
 
# File 'lib/redis.rb', line 29

def initialize(options = {})
  @original_client = @client = Client.new(options)

  super() # Monitor#initialize
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(command, *args) ⇒ Object 



2425
2426
2427
2428
2429
 
# File 'lib/redis.rb', line 2425

def method_missing(command, *args)
  synchronize do |client|
    client.call([command] + args)
  end
end

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.



10
11
12
 
# File 'lib/redis.rb', line 10

def client
  @client
end

Class Method Details

.connect(options = {}) ⇒ Object

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.



15
16
17
 
# File 'lib/redis.rb', line 15

def self.connect(options = {})
  new(options)
end

.current ⇒ Object 



19
20
21
 
# File 'lib/redis.rb', line 19

def self.current
  @current ||= Redis.new
end

.current=(redis) ⇒ Object 



23
24
25
 
# File 'lib/redis.rb', line 23

def self.current=(redis)
  @current = redis
end

.deprecate(message, trace = caller[0]) ⇒ Object 



6
7
8
 
# File 'lib/redis.rb', line 6

def self.deprecate(message, trace = caller[0])
  $stderr.puts "\n#{message} (in #{trace})"
end

Instance Method Details

#_bpop(cmd, args) ⇒ Object 



1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
 
# File 'lib/redis.rb', line 1016

def _bpop(cmd, args)
  options = {}

  case args.last
  when Hash
    options = args.pop
  when Integer
    # Issue deprecation notice in obnoxious mode...
    options[:timeout] = args.pop
  end

  if args.size > 1
    # Issue deprecation notice in obnoxious mode...
  end

  keys = args.flatten
  timeout = options[:timeout] || 0

  synchronize do |client|
    command = [cmd, keys, timeout]
    timeout += client.timeout if timeout > 0
    client.call_with_timeout(command, timeout)
  end
end

#_eval(cmd, args) ⇒ Object 



2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
 
# File 'lib/redis.rb', line 2179

def _eval(cmd, args)
  script = args.shift
  options = args.pop if args.last.is_a?(Hash)
  options ||= {}

  keys = args.shift || options[:keys] || []
  argv = args.shift || options[:argv] || []

  synchronize do |client|
    client.call([cmd, script, keys.length] + keys + argv)
  end
end

#_scan(command, cursor, args, options = {}, &block) ⇒ Object 



2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
 
# File 'lib/redis.rb', line 2242

def _scan(command, cursor, args, options = {}, &block)
  # SSCAN/ZSCAN/HSCAN already prepend the key to +args+.

  args << cursor

  if match = options[:match]
    args.concat(["MATCH", match])
  end

  if count = options[:count]
    args.concat(["COUNT", count])
  end

  synchronize do |client|
    client.call([command] + args, &block)
  end
end

#append(key, value) ⇒ Fixnum

Append a value to a key.

Parameters:

  • key (String)
  • value (String) —

    value to append

Returns:

  • (Fixnum) —

    length of the string after appending



878
879
880
881
882
 
# File 'lib/redis.rb', line 878

def append(key, value)
  synchronize do |client|
    client.call([:append, key, value])
  end
end

#auth(password) ⇒ String

Authenticate to the server.

Parameters:

  • password (String) —

    must match the password specified in the requirepass directive in the configuration file

Returns:

  • (String) —

    OK



61
62
63
64
65
 
# File 'lib/redis.rb', line 61

def auth(password)
  synchronize do |client|
    client.call([:auth, password])
  end
end

#bgrewriteaof ⇒ String

Asynchronously rewrite the append-only file.

Returns:

  • (String) —

    OK



114
115
116
117
118
 
# File 'lib/redis.rb', line 114

def bgrewriteaof
  synchronize do |client|
    client.call([:bgrewriteaof])
  end
end

#bgsave ⇒ String

Asynchronously save the dataset to disk.

Returns:

  • (String) —

    OK



123
124
125
126
127
 
# File 'lib/redis.rb', line 123

def bgsave
  synchronize do |client|
    client.call([:bgsave])
  end
end

#bitcount(key, start = 0, stop = -1)) ⇒ Fixnum

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

Parameters:

  • key (String)
  • start (Fixnum) (defaults to: 0) —

    start index

  • stop (Fixnum) (defaults to: -1)) —

    stop index

Returns:

  • (Fixnum) —

    the number of bits set to 1



890
891
892
893
894
 
# File 'lib/redis.rb', line 890

def bitcount(key, start = 0, stop = -1)
  synchronize do |client|
    client.call([:bitcount, key, start, stop])
  end
end

#bitop(operation, destkey, *keys) ⇒ Fixnum

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

Parameters:

  • operation (String) —

    e.g. and, or, xor, not

  • destkey (String) —

    destination key

  • keys (String, Array<String>) —

    one or more source keys to perform operation

Returns:

  • (Fixnum) —

    the length of the string stored in destkey



902
903
904
905
906
 
# File 'lib/redis.rb', line 902

def bitop(operation, destkey, *keys)
  synchronize do |client|
    client.call([:bitop, operation, destkey] + keys)
  end
end

#blpop(*args) ⇒ nil, [String, String]

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

Examples:

With timeout

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

Without timeout

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

Blocking pop on multiple lists

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

Parameters:

  • keys (String, Array<String>) —

    one or more keys to perform the blocking pop on

  • options (Hash) —
    • :timeout => Fixnum: timeout in seconds, defaults to no timeout

Returns:

  • (nil, [String, String]) —
    • nil when the operation timed out
    • tuple of the list that was popped from and element was popped otherwise


1062
1063
1064
 
# File 'lib/redis.rb', line 1062

def blpop(*args)
  _bpop(:blpop, args)
end

#brpop(*args) ⇒ nil, [String, String]

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

Parameters:

  • keys (String, Array<String>) —

    one or more keys to perform the blocking pop on

  • options (Hash) —
    • :timeout => Fixnum: timeout in seconds, defaults to no timeout

Returns:

  • (nil, [String, String]) —
    • nil when the operation timed out
    • tuple of the list that was popped from and element was popped otherwise

See Also:



1078
1079
1080
 
# File 'lib/redis.rb', line 1078

def brpop(*args)
  _bpop(:brpop, args)
end

#brpoplpush(source, destination, options = {}) ⇒ nil, String

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

Parameters:

  • source (String) —

    source key

  • destination (String) —

    destination key

  • options (Hash) (defaults to: {}) —
    • :timeout => Fixnum: timeout in seconds, defaults to no timeout

Returns:

  • (nil, String) —
    • nil when the operation timed out
    • the element was popped and pushed otherwise


1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
 
# File 'lib/redis.rb', line 1093

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

#config(action, *args) ⇒ String, Hash

Get or set server configuration parameters.

Parameters:

  • action (String) —

    e.g. get, set, resetstat

Returns:

  • (String, Hash) —

    string reply, or hash when retrieving more than one property with CONFIG GET



134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/redis.rb', line 134

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

#connected? ⇒ Boolean

Test whether or not the client is connected

Returns:

  • (Boolean) 


52
53
54
 
# File 'lib/redis.rb', line 52

def connected?
  @original_client.connected?
end

#dbsize ⇒ Fixnum

Return the number of keys in the selected database.

Returns:

  • (Fixnum) 


149
150
151
152
153
 
# File 'lib/redis.rb', line 149

def dbsize
  synchronize do |client|
    client.call([:dbsize])
  end
end

#debug(*args) ⇒ Object 



155
156
157
158
159
 
# File 'lib/redis.rb', line 155

def debug(*args)
  synchronize do |client|
    client.call([:debug] + args)
  end
end

#decr(key) ⇒ Fixnum

Decrement the integer value of a key by one.

Examples:

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

Parameters:

  • key (String)

Returns:

  • (Fixnum) —

    value after decrementing it



581
582
583
584
585
 
# File 'lib/redis.rb', line 581

def decr(key)
  synchronize do |client|
    client.call([:decr, key])
  end
end

#decrby(key, decrement) ⇒ Fixnum

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

Examples:

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

Parameters:

  • key (String)
  • decrement (Fixnum)

Returns:

  • (Fixnum) —

    value after decrementing it



596
597
598
599
600
 
# File 'lib/redis.rb', line 596

def decrby(key, decrement)
  synchronize do |client|
    client.call([:decrby, key, decrement])
  end
end

#del(*keys) ⇒ Fixnum

Delete one or more keys.

Parameters:

  • keys (String, Array<String>)

Returns:

  • (Fixnum) —

    number of keys that were deleted



413
414
415
416
417
 
# File 'lib/redis.rb', line 413

def del(*keys)
  synchronize do |client|
    client.call([:del] + keys)
  end
end

#discard ⇒ Object

Discard all commands issued after MULTI.

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

See Also:



2125
2126
2127
2128
2129
 
# File 'lib/redis.rb', line 2125

def discard
  synchronize do |client|
    client.call([:discard])
  end
end

#dump(key) ⇒ String

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

Parameters:

  • key (String)

Returns:

  • (String) —

    serialized_value



371
372
373
374
375
 
# File 'lib/redis.rb', line 371

def dump(key)
  synchronize do |client|
    client.call([:dump, key])
  end
end

#echo(value) ⇒ String

Echo the given string.

Parameters:

  • value (String)

Returns:

  • (String) 


91
92
93
94
95
 
# File 'lib/redis.rb', line 91

def echo(value)
  synchronize do |client|
    client.call([:echo, value])
  end
end

#eval(*args) ⇒ Object

Evaluate Lua script.

Examples:

EVAL without KEYS nor ARGV

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

EVAL with KEYS and ARGV as array arguments

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

EVAL with KEYS and ARGV in a hash argument

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

Parameters:

  • keys (Array<String>) —

    optional array with keys to pass to the script

  • argv (Array<String>) —

    optional array with arguments to pass to the script

  • options (Hash) —
    • :keys => Array<String>: optional array with keys to pass to the script
    • :argv => Array<String>: optional array with arguments to pass to the script

Returns:

  • depends on the script

See Also:



2213
2214
2215
 
# File 'lib/redis.rb', line 2213

def eval(*args)
  _eval(:eval, args)
end

#evalsha(*args) ⇒ Object

Evaluate Lua script by its SHA.

Examples:

EVALSHA without KEYS nor ARGV

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

EVALSHA with KEYS and ARGV as array arguments

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

EVALSHA with KEYS and ARGV in a hash argument

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

Parameters:

  • keys (Array<String>) —

    optional array with keys to pass to the script

  • argv (Array<String>) —

    optional array with arguments to pass to the script

  • options (Hash) —
    • :keys => Array<String>: optional array with keys to pass to the script
    • :argv => Array<String>: optional array with arguments to pass to the script

Returns:

  • depends on the script

See Also:



2238
2239
2240
 
# File 'lib/redis.rb', line 2238

def evalsha(*args)
  _eval(:evalsha, args)
end

#exec ⇒ nil, Array<...>

Execute all commands issued after MULTI.

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

Returns:

  • (nil, Array<...>) —
    • when commands were not executed, nil
    • when commands were executed, an array with their replies

See Also:



2111
2112
2113
2114
2115
 
# File 'lib/redis.rb', line 2111

def exec
  synchronize do |client|
    client.call([:exec])
  end
end

#exists(key) ⇒ Boolean

Determine if a key exists.

Parameters:

  • key (String)

Returns:

  • (Boolean) 


423
424
425
426
427
 
# File 'lib/redis.rb', line 423

def exists(key)
  synchronize do |client|
    client.call([:exists, key], &_boolify)
  end
end

#expire(key, seconds) ⇒ Boolean

Set a key's time to live in seconds.

Parameters:

  • key (String)
  • seconds (Fixnum) —

    time to live

Returns:

  • (Boolean) —

    whether the timeout was set or not



306
307
308
309
310
 
# File 'lib/redis.rb', line 306

def expire(key, seconds)
  synchronize do |client|
    client.call([:expire, key, seconds], &_boolify)
  end
end

#expireat(key, unix_time) ⇒ Boolean

Set the expiration for a key as a UNIX timestamp.

Parameters:

  • key (String)
  • unix_time (Fixnum) —

    expiry time specified as a UNIX timestamp

Returns:

  • (Boolean) —

    whether the timeout was set or not



317
318
319
320
321
 
# File 'lib/redis.rb', line 317

def expireat(key, unix_time)
  synchronize do |client|
    client.call([:expireat, key, unix_time], &_boolify)
  end
end

#flushall ⇒ String

Remove all keys from all databases.

Returns:

  • (String) —

    OK



164
165
166
167
168
 
# File 'lib/redis.rb', line 164

def flushall
  synchronize do |client|
    client.call([:flushall])
  end
end

#flushdb ⇒ String

Remove all keys from the current database.

Returns:

  • (String) —

    OK



173
174
175
176
177
 
# File 'lib/redis.rb', line 173

def flushdb
  synchronize do |client|
    client.call([:flushdb])
  end
end

#get(key) ⇒ String Also known as: []

Get the value of a key.

Parameters:

  • key (String)

Returns:

  • (String) 


781
782
783
784
785
 
# File 'lib/redis.rb', line 781

def get(key)
  synchronize do |client|
    client.call([:get, key])
  end
end

#getbit(key, offset) ⇒ Fixnum

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

Parameters:

  • key (String)
  • offset (Fixnum) —

    bit offset

Returns:

  • (Fixnum) —

    0 or 1



867
868
869
870
871
 
# File 'lib/redis.rb', line 867

def getbit(key, offset)
  synchronize do |client|
    client.call([:getbit, key, offset])
  end
end

#getrange(key, start, stop) ⇒ Fixnum

Get a substring of the string stored at a key.

Parameters:

  • key (String)
  • start (Fixnum) —

    zero-based start offset

  • stop (Fixnum) —

    zero-based end offset. Use -1 for representing the end of the string

Returns:

  • (Fixnum) —

    0 or 1



844
845
846
847
848
 
# File 'lib/redis.rb', line 844

def getrange(key, start, stop)
  synchronize do |client|
    client.call([:getrange, key, start, stop])
  end
end

#getset(key, value) ⇒ String

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

Parameters:

  • key (String)
  • value (String) —

    value to replace the current value with

Returns:

  • (String) —

    the old value stored in the key, or nil if the key did not exist



914
915
916
917
918
 
# File 'lib/redis.rb', line 914

def getset(key, value)
  synchronize do |client|
    client.call([:getset, key, value.to_s])
  end
end

#hdel(key, field) ⇒ Fixnum

Delete one or more hash fields.

Parameters:

  • key (String)
  • field (String, Array<String>)

Returns:

  • (Fixnum) —

    the number of fields that were removed from the hash



1867
1868
1869
1870
1871
 
# File 'lib/redis.rb', line 1867

def hdel(key, field)
  synchronize do |client|
    client.call([:hdel, key, field])
  end
end

#hexists(key, field) ⇒ Boolean

Determine if a hash field exists.

Parameters:

  • key (String)
  • field (String)

Returns:

  • (Boolean) —

    whether or not the field exists in the hash



1878
1879
1880
1881
1882
 
# File 'lib/redis.rb', line 1878

def hexists(key, field)
  synchronize do |client|
    client.call([:hexists, key, field], &_boolify)
  end
end

#hget(key, field) ⇒ String

Get the value of a hash field.

Parameters:

  • key (String)
  • field (String)

Returns:

  • (String) 


1818
1819
1820
1821
1822
 
# File 'lib/redis.rb', line 1818

def hget(key, field)
  synchronize do |client|
    client.call([:hget, key, field])
  end
end

#hgetall(key) ⇒ Hash<String, String>

Get all the fields and values in a hash.

Parameters:

  • key (String)

Returns:

  • (Hash<String, String>) 


1932
1933
1934
1935
1936
 
# File 'lib/redis.rb', line 1932

def hgetall(key)
  synchronize do |client|
    client.call([:hgetall, key], &_hashify)
  end
end

#hincrby(key, field, increment) ⇒ Fixnum

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

Parameters:

  • key (String)
  • field (String)
  • increment (Fixnum)

Returns:

  • (Fixnum) —

    value of the field after incrementing it



1890
1891
1892
1893
1894
 
# File 'lib/redis.rb', line 1890

def hincrby(key, field, increment)
  synchronize do |client|
    client.call([:hincrby, key, field, increment])
  end
end

#hincrbyfloat(key, field, increment) ⇒ Float

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

Parameters:

  • key (String)
  • field (String)
  • increment (Float)

Returns:

  • (Float) —

    value of the field after incrementing it



1902
1903
1904
1905
1906
 
# File 'lib/redis.rb', line 1902

def hincrbyfloat(key, field, increment)
  synchronize do |client|
    client.call([:hincrbyfloat, key, field, increment], &_floatify)
  end
end

#hkeys(key) ⇒ Array<String>

Get all the fields in a hash.

Parameters:

  • key (String)

Returns:

  • (Array<String>) 


1912
1913
1914
1915
1916
 
# File 'lib/redis.rb', line 1912

def hkeys(key)
  synchronize do |client|
    client.call([:hkeys, key])
  end
end

#hlen(key) ⇒ Fixnum

Get the number of fields in a hash.

Parameters:

  • key (String)

Returns:

  • (Fixnum) —

    number of fields in the hash



1751
1752
1753
1754
1755
 
# File 'lib/redis.rb', line 1751

def hlen(key)
  synchronize do |client|
    client.call([:hlen, key])
  end
end

#hmget(key, *fields, &blk) ⇒ Array<String>

Get the values of all the given hash fields.

Examples:

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

Parameters:

  • key (String)
  • fields (Array<String>) —

    array of fields

Returns:

  • (Array<String>) —

    an array of values for the specified fields

See Also:



1835
1836
1837
1838
1839
 
# File 'lib/redis.rb', line 1835

def hmget(key, *fields, &blk)
  synchronize do |client|
    client.call([:hmget, key] + fields, &blk)
  end
end

#hmset(key, *attrs) ⇒ Object

Set one or more hash values.

Examples:

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

Parameters:

  • key (String)
  • attrs (Array<String>) —

    array of fields and values

See Also:



1792
1793
1794
1795
1796
 
# File 'lib/redis.rb', line 1792

def hmset(key, *attrs)
  synchronize do |client|
    client.call([:hmset, key] + attrs)
  end
end

#hscan(key, cursor, options = {}) ⇒ String, Array<[String, String]>

Scan a hash

Examples:

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

redis.hscan("hash", 0)

Parameters:

  • cursor: (String, Integer) —

    the cursor of the iteration

  • options (Hash) (defaults to: {}) —
    • :match => String: only return keys matching the pattern
    • :count => Integer: return count keys at most per iteration

Returns:

  • (String, Array<[String, String]>) —

    the next cursor and all found keys



2315
2316
2317
2318
2319
 
# File 'lib/redis.rb', line 2315

def hscan(key, cursor, options={})
  _scan(:hscan, cursor, [key], options) do |reply|
    [reply[0], _pairify(reply[1])]
  end
end

#hscan_each(key, options = {}, &block) ⇒ Enumerator

Scan a hash

Examples:

Retrieve all of the key/value pairs in a hash

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

Parameters:

  • options (Hash) (defaults to: {}) —
    • :match => String: only return keys matching the pattern
    • :count => Integer: return count keys at most per iteration

Returns:

  • (Enumerator) —

    an enumerator for all found keys



2332
2333
2334
2335
2336
2337
2338
2339
2340
 
# File 'lib/redis.rb', line 2332

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

#hset(key, field, value) ⇒ Boolean

Set the string value of a hash field.

Parameters:

  • key (String)
  • field (String)
  • value (String)

Returns:

  • (Boolean) —

    whether or not the field was added to the hash



1763
1764
1765
1766
1767
 
# File 'lib/redis.rb', line 1763

def hset(key, field, value)
  synchronize do |client|
    client.call([:hset, key, field, value], &_boolify)
  end
end

#hsetnx(key, field, value) ⇒ Boolean

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

Parameters:

  • key (String)
  • field (String)
  • value (String)

Returns:

  • (Boolean) —

    whether or not the field was added to the hash



1775
1776
1777
1778
1779
 
# File 'lib/redis.rb', line 1775

def hsetnx(key, field, value)
  synchronize do |client|
    client.call([:hsetnx, key, field, value], &_boolify)
  end
end

#hvals(key) ⇒ Array<String>

Get all the values in a hash.

Parameters:

  • key (String)

Returns:

  • (Array<String>) 


1922
1923
1924
1925
1926
 
# File 'lib/redis.rb', line 1922

def hvals(key)
  synchronize do |client|
    client.call([:hvals, key])
  end
end

#id ⇒ Object 



2417
2418
2419
 
# File 'lib/redis.rb', line 2417

def id
  @original_client.id
end

#incr(key) ⇒ Fixnum

Increment the integer value of a key by one.

Examples:

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

Parameters:

  • key (String)

Returns:

  • (Fixnum) —

    value after incrementing it



610
611
612
613
614
 
# File 'lib/redis.rb', line 610

def incr(key)
  synchronize do |client|
    client.call([:incr, key])
  end
end

#incrby(key, increment) ⇒ Fixnum

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

Examples:

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

Parameters:

  • key (String)
  • increment (Fixnum)

Returns:

  • (Fixnum) —

    value after incrementing it



625
626
627
628
629
 
# File 'lib/redis.rb', line 625

def incrby(key, increment)
  synchronize do |client|
    client.call([:incrby, key, increment])
  end
end

#incrbyfloat(key, increment) ⇒ Float

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

Examples:

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

Parameters:

  • key (String)
  • increment (Float)

Returns:

  • (Float) —

    value after incrementing it



640
641
642
643
644
 
# File 'lib/redis.rb', line 640

def incrbyfloat(key, increment)
  synchronize do |client|
    client.call([:incrbyfloat, key, increment], &_floatify)
  end
end

#info(cmd = nil) ⇒ Hash<String, String>

Get information and statistics about the server.

Parameters:

  • cmd (String, Symbol) (defaults to: nil) —

    e.g. "commandstats"

Returns:

  • (Hash<String, String>) 


183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/redis.rb', line 183

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

#inspect ⇒ Object 



2421
2422
2423
 
# File 'lib/redis.rb', line 2421

def inspect
  "#<Redis client v#{Redis::VERSION} for #{id}>"
end

#keys(pattern = "*") ⇒ Array<String>

Find all keys matching the given pattern.

Parameters:

  • pattern (String) (defaults to: "*")

Returns:

  • (Array<String>) 


433
434
435
436
437
438
439
440
441
442
443
 
# File 'lib/redis.rb', line 433

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

#lastsave ⇒ Fixnum

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

Returns:

  • (Fixnum) 


208
209
210
211
212
 
# File 'lib/redis.rb', line 208

def lastsave
  synchronize do |client|
    client.call([:lastsave])
  end
end

#lindex(key, index) ⇒ String

Get an element from a list by its index.

Parameters:

  • key (String)
  • index (Fixnum)

Returns:

  • (String) 


1114
1115
1116
1117
1118
 
# File 'lib/redis.rb', line 1114

def lindex(key, index)
  synchronize do |client|
    client.call([:lindex, key, index])
  end
end

#linsert(key, where, pivot, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • where (String, Symbol) —

    BEFORE or AFTER

  • pivot (String) —

    reference element

  • value (String)

Returns:

  • (Fixnum) —

    length of the list after the insert operation, or -1 when the element pivot was not found



1128
1129
1130
1131
1132
 
# File 'lib/redis.rb', line 1128

def linsert(key, where, pivot, value)
  synchronize do |client|
    client.call([:linsert, key, where, pivot, value])
  end
end

#llen(key) ⇒ Fixnum

Get the length of a list.

Parameters:

  • key (String)

Returns:

  • (Fixnum) 


935
936
937
938
939
 
# File 'lib/redis.rb', line 935

def llen(key)
  synchronize do |client|
    client.call([:llen, key])
  end
end

#lpop(key) ⇒ String

Remove and get the first element in a list.

Parameters:

  • key (String)

Returns:

  • (String) 


989
990
991
992
993
 
# File 'lib/redis.rb', line 989

def lpop(key)
  synchronize do |client|
    client.call([:lpop, key])
  end
end

#lpush(key, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • string (String, Array) —

    value, or array of string values to push

Returns:

  • (Fixnum) —

    the length of the list after the push operation



946
947
948
949
950
 
# File 'lib/redis.rb', line 946

def lpush(key, value)
  synchronize do |client|
    client.call([:lpush, key, value])
  end
end

#lpushx(key, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • value (String)

Returns:

  • (Fixnum) —

    the length of the list after the push operation



957
958
959
960
961
 
# File 'lib/redis.rb', line 957

def lpushx(key, value)
  synchronize do |client|
    client.call([:lpushx, key, value])
  end
end

#lrange(key, start, stop) ⇒ Array<String>

Get a range of elements from a list.

Parameters:

  • key (String)
  • start (Fixnum) —

    start index

  • stop (Fixnum) —

    stop index

Returns:

  • (Array<String>) 


1140
1141
1142
1143
1144
 
# File 'lib/redis.rb', line 1140

def lrange(key, start, stop)
  synchronize do |client|
    client.call([:lrange, key, start, stop])
  end
end

#lrem(key, count, value) ⇒ Fixnum

Remove elements from a list.

Parameters:

  • key (String)
  • count (Fixnum) —

    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.

  • value (String)

Returns:

  • (Fixnum) —

    the number of removed elements



1155
1156
1157
1158
1159
 
# File 'lib/redis.rb', line 1155

def lrem(key, count, value)
  synchronize do |client|
    client.call([:lrem, key, count, value])
  end
end

#lset(key, index, value) ⇒ String

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

Parameters:

  • key (String)
  • index (Fixnum)
  • value (String)

Returns:

  • (String) —

    OK



1167
1168
1169
1170
1171
 
# File 'lib/redis.rb', line 1167

def lset(key, index, value)
  synchronize do |client|
    client.call([:lset, key, index, value])
  end
end

#ltrim(key, start, stop) ⇒ String

Trim a list to the specified range.

Parameters:

  • key (String)
  • start (Fixnum) —

    start index

  • stop (Fixnum) —

    stop index

Returns:

  • (String) —

    OK



1179
1180
1181
1182
1183
 
# File 'lib/redis.rb', line 1179

def ltrim(key, start, stop)
  synchronize do |client|
    client.call([:ltrim, key, start, stop])
  end
end

#mapped_hmget(key, *fields) ⇒ Hash

Get the values of all the given hash fields.

Examples:

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

Parameters:

  • key (String)
  • fields (Array<String>) —

    array of fields

Returns:

  • (Hash) —

    a hash mapping the specified fields to their values

See Also:



1852
1853
1854
1855
1856
1857
1858
1859
1860
 
# File 'lib/redis.rb', line 1852

def mapped_hmget(key, *fields)
  hmget(key, *fields) do |reply|
    if reply.kind_of?(Array)
      Hash[fields.zip(reply)]
    else
      reply
    end
  end
end

#mapped_hmset(key, hash) ⇒ Object

Set one or more hash values.

Examples:

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

Parameters:

  • key (String)
  • hash (Hash) —

    fields mapping to values

See Also:



1809
1810
1811
 
# File 'lib/redis.rb', line 1809

def mapped_hmset(key, hash)
  hmset(key, hash.to_a.flatten)
end

#mapped_mget(*keys) ⇒ Hash

Get the values of all the given keys.

Examples:

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

Parameters:

  • keys (Array<String>) —

    array of keys

Returns:

  • (Hash) —

    a hash mapping the specified keys to their values

See Also:



815
816
817
818
819
820
821
822
823
 
# File 'lib/redis.rb', line 815

def mapped_mget(*keys)
  mget(*keys) do |reply|
    if reply.kind_of?(Array)
      Hash[keys.zip(reply)]
    else
      reply
    end
  end
end

#mapped_mset(hash) ⇒ Object

Set one or more values.

Examples:

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

Parameters:

  • hash (Hash) —

    keys mapping to values

See Also:



743
744
745
 
# File 'lib/redis.rb', line 743

def mapped_mset(hash)
  mset(hash.to_a.flatten)
end

#mapped_msetnx(hash) ⇒ Boolean

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

Examples:

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

Parameters:

  • hash (Hash) —

    keys mapping to values

Returns:

  • (Boolean) —

    whether or not all values were set

See Also:



773
774
775
 
# File 'lib/redis.rb', line 773

def mapped_msetnx(hash)
  msetnx(hash.to_a.flatten)
end

#mget(*keys, &blk) ⇒ Array<String>

Get the values of all the given keys.

Examples:

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

Parameters:

  • keys (Array<String>)

Returns:

  • (Array<String>) —

    an array of values for the specified keys

See Also:



799
800
801
802
803
 
# File 'lib/redis.rb', line 799

def mget(*keys, &blk)
  synchronize do |client|
    client.call([:mget] + keys, &blk)
  end
end

#migrate(key, options) ⇒ String

Transfer a key from the connected instance to another instance.

Parameters:

  • key (String)
  • options (Hash) —
    • :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)

Returns:

  • (String) —

    "OK"



398
399
400
401
402
403
404
405
406
407
 
# File 'lib/redis.rb', line 398

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

#monitor {|line| ... } ⇒ Object

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

There is no way to interrupt this command.

Yields:

  • a block to be called for every line of output

Yield Parameters:

  • line (String) —

    timestamp and command that was executed



220
221
222
223
224
 
# File 'lib/redis.rb', line 220

def monitor(&block)
  synchronize do |client|
    client.call_loop([:monitor], &block)
  end
end

#move(key, db) ⇒ Boolean

Move a key to another database.

Examples:

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"

Parameters:

  • key (String)
  • db (Fixnum)

Returns:

  • (Boolean) —

    whether the key was moved or not



464
465
466
467
468
 
# File 'lib/redis.rb', line 464

def move(key, db)
  synchronize do |client|
    client.call([:move, key, db], &_boolify)
  end
end

#mset(*args) ⇒ Object

Set one or more values.

Examples:

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

Parameters:

  • args (Array<String>) —

    array of keys and values

See Also:



727
728
729
730
731
 
# File 'lib/redis.rb', line 727

def mset(*args)
  synchronize do |client|
    client.call([:mset] + args)
  end
end

#msetnx(*args) ⇒ Boolean

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

Examples:

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

Parameters:

  • args (Array<String>) —

    array of keys and values

Returns:

  • (Boolean) —

    whether or not all values were set

See Also:



757
758
759
760
761
 
# File 'lib/redis.rb', line 757

def msetnx(*args)
  synchronize do |client|
    client.call([:msetnx] + args, &_boolify)
  end
end

#multi {|multi| ... } ⇒ String, Array<...>

Mark the start of a transaction block.

Passing a block is optional.

Examples:

With a block

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

Without a block

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

Yields:

  • (multi) —

    the commands that are called inside this block are cached and written to the server upon returning from it

Yield Parameters:

Returns:

  • (String, Array<...>) —
    • when a block is not given, OK
    • when a block is given, an array with replies

See Also:



2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
 
# File 'lib/redis.rb', line 2084

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

#object(*args) ⇒ Object 



470
471
472
473
474
 
# File 'lib/redis.rb', line 470

def object(*args)
  synchronize do |client|
    client.call([:object] + args)
  end
end

#persist(key) ⇒ Boolean

Remove the expiration from a key.

Parameters:

  • key (String)

Returns:

  • (Boolean) —

    whether the timeout was removed or not



295
296
297
298
299
 
# File 'lib/redis.rb', line 295

def persist(key)
  synchronize do |client|
    client.call([:persist, key], &_boolify)
  end
end

#pexpire(key, milliseconds) ⇒ Boolean

Set a key's time to live in milliseconds.

Parameters:

  • key (String)
  • milliseconds (Fixnum) —

    time to live

Returns:

  • (Boolean) —

    whether the timeout was set or not



339
340
341
342
343
 
# File 'lib/redis.rb', line 339

def pexpire(key, milliseconds)
  synchronize do |client|
    client.call([:pexpire, key, milliseconds], &_boolify)
  end
end

#pexpireat(key, ms_unix_time) ⇒ Boolean

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

Parameters:

  • key (String)
  • ms_unix_time (Fixnum) —

    expiry time specified as number of milliseconds from UNIX Epoch.

Returns:

  • (Boolean) —

    whether the timeout was set or not



350
351
352
353
354
 
# File 'lib/redis.rb', line 350

def pexpireat(key, ms_unix_time)
  synchronize do |client|
    client.call([:pexpireat, key, ms_unix_time], &_boolify)
  end
end

#ping ⇒ String

Ping the server.

Returns:

  • (String) —

    PONG



81
82
83
84
85
 
# File 'lib/redis.rb', line 81

def ping
  synchronize do |client|
    client.call([:ping])
  end
end

#pipelined ⇒ Object 



2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
 
# File 'lib/redis.rb', line 2042

def pipelined
  synchronize do |client|
    begin
      original, @client = @client, Pipeline.new
      yield(self)
      original.call_pipeline(@client)
    ensure
      @client = original
    end
  end
end

#psetex(key, ttl, value) ⇒ Object

Set the time to live in milliseconds of a key.

Parameters:

  • key (String)
  • ttl (Fixnum)
  • value (String) 


700
701
702
703
704
 
# File 'lib/redis.rb', line 700

def psetex(key, ttl, value)
  synchronize do |client|
    client.call([:psetex, key, ttl, value.to_s])
  end
end

#psubscribe(*channels, &block) ⇒ Object

Listen for messages published to channels matching the given patterns.



1967
1968
1969
1970
1971
 
# File 'lib/redis.rb', line 1967

def psubscribe(*channels, &block)
  synchronize do |client|
    _subscription(:psubscribe, channels, block)
  end
end

#pttl(key) ⇒ Fixnum

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

Parameters:

  • key (String)

Returns:

  • (Fixnum) —

    remaining time to live in milliseconds, or -1 if the key does not exist or does not have a timeout



361
362
363
364
365
 
# File 'lib/redis.rb', line 361

def pttl(key)
  synchronize do |client|
    client.call([:pttl, key])
  end
end

#publish(channel, message) ⇒ Object

Post a message to a channel.



1939
1940
1941
1942
1943
 
# File 'lib/redis.rb', line 1939

def publish(channel, message)
  synchronize do |client|
    client.call([:publish, channel, message])
  end
end

#punsubscribe(*channels) ⇒ Object

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



1974
1975
1976
1977
1978
1979
 
# File 'lib/redis.rb', line 1974

def punsubscribe(*channels)
  synchronize do |client|
    raise RuntimeError, "Can't unsubscribe if not subscribed." unless subscribed?
    client.punsubscribe(*channels)
  end
end

#quit ⇒ String

Close the connection.

Returns:

  • (String) —

    OK



100
101
102
103
104
105
106
107
108
109
 
# File 'lib/redis.rb', line 100

def quit
  synchronize do |client|
    begin
      client.call([:quit])
    rescue ConnectionError
    ensure
      client.disconnect
    end
  end
end

#randomkey ⇒ String

Return a random key from the keyspace.

Returns:

  • (String) 


479
480
481
482
483
 
# File 'lib/redis.rb', line 479

def randomkey
  synchronize do |client|
    client.call([:randomkey])
  end
end

#rename(old_name, new_name) ⇒ String

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

Parameters:

  • old_name (String)
  • new_name (String)

Returns:

  • (String) —

    OK



490
491
492
493
494
 
# File 'lib/redis.rb', line 490

def rename(old_name, new_name)
  synchronize do |client|
    client.call([:rename, old_name, new_name])
  end
end

#renamenx(old_name, new_name) ⇒ Boolean

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

Parameters:

  • old_name (String)
  • new_name (String)

Returns:

  • (Boolean) —

    whether the key was renamed or not



501
502
503
504
505
 
# File 'lib/redis.rb', line 501

def renamenx(old_name, new_name)
  synchronize do |client|
    client.call([:renamenx, old_name, new_name], &_boolify)
  end
end

#restore(key, ttl, serialized_value) ⇒ Object

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

Parameters:

  • key (String)
  • ttl (String)
  • serialized_value (String) 


383
384
385
386
387
 
# File 'lib/redis.rb', line 383

def restore(key, ttl, serialized_value)
  synchronize do |client|
    client.call([:restore, key, ttl, serialized_value])
  end
end

#rpop(key) ⇒ String

Remove and get the last element in a list.

Parameters:

  • key (String)

Returns:

  • (String) 


999
1000
1001
1002
1003
 
# File 'lib/redis.rb', line 999

def rpop(key)
  synchronize do |client|
    client.call([:rpop, key])
  end
end

#rpoplpush(source, destination) ⇒ nil, String

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

Parameters:

  • source (String) —

    source key

  • destination (String) —

    destination key

Returns:

  • (nil, String) —

    the element, or nil when the source key does not exist



1010
1011
1012
1013
1014
 
# File 'lib/redis.rb', line 1010

def rpoplpush(source, destination)
  synchronize do |client|
    client.call([:rpoplpush, source, destination])
  end
end

#rpush(key, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • value (String)

Returns:

  • (Fixnum) —

    the length of the list after the push operation



968
969
970
971
972
 
# File 'lib/redis.rb', line 968

def rpush(key, value)
  synchronize do |client|
    client.call([:rpush, key, value])
  end
end

#rpushx(key, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • value (String)

Returns:

  • (Fixnum) —

    the length of the list after the push operation



979
980
981
982
983
 
# File 'lib/redis.rb', line 979

def rpushx(key, value)
  synchronize do |client|
    client.call([:rpushx, key, value])
  end
end

#sadd(key, member) ⇒ Boolean, Fixnum

Add one or more members to a set.

Parameters:

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

    one member, or array of members

Returns:

  • (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



1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
 
# File 'lib/redis.rb', line 1203

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

#save ⇒ String

Synchronously save the dataset to disk.

Returns:

  • (String) 


229
230
231
232
233
 
# File 'lib/redis.rb', line 229

def save
  synchronize do |client|
    client.call([:save])
  end
end

#scan(cursor, options = {}) ⇒ String+

Scan the keyspace

Examples:

Retrieve the first batch of keys

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

Retrieve a batch of keys matching a pattern

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

Parameters:

  • cursor: (String, Integer) —

    the cursor of the iteration

  • options (Hash) (defaults to: {}) —
    • :match => String: only return keys matching the pattern
    • :count => Integer: return count keys at most per iteration

Returns:

  • (String, Array<String>) —

    the next cursor and all found keys



2275
2276
2277
 
# File 'lib/redis.rb', line 2275

def scan(cursor, options={})
  _scan(:scan, cursor, [], options)
end

#scan_each(options = {}, &block) ⇒ Enumerator

Scan the keyspace

Examples:

Retrieve all of the keys (with possible duplicates)

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

Execute block for each key matching a pattern

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

Parameters:

  • options (Hash) (defaults to: {}) —
    • :match => String: only return keys matching the pattern
    • :count => Integer: return count keys at most per iteration

Returns:

  • (Enumerator) —

    an enumerator for all found keys



2294
2295
2296
2297
2298
2299
2300
2301
2302
 
# File 'lib/redis.rb', line 2294

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

#scard(key) ⇒ Fixnum

Get the number of members in a set.

Parameters:

  • key (String)

Returns:

  • (Fixnum) 


1189
1190
1191
1192
1193
 
# File 'lib/redis.rb', line 1189

def scard(key)
  synchronize do |client|
    client.call([:scard, key])
  end
end

#script(subcommand, *args) ⇒ String, ...

Control remote script registry.

Examples:

Load a script

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

Check if a script exists

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

Check if multiple scripts exist

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

Flush the script registry

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

Kill a running script

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

Parameters:

  • subcommand (String) —

    e.g. exists, flush, load, kill

  • args (Array<String>) —

    depends on subcommand

Returns:

  • (String, Boolean, Array<Boolean>, ...) —

    depends on subcommand

See Also:



2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
 
# File 'lib/redis.rb', line 2155

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

#sdiff(*keys) ⇒ Array<String>

Subtract multiple sets.

Parameters:

  • keys (String, Array<String>) —

    keys pointing to sets to subtract

Returns:

  • (Array<String>) —

    members in the difference



1301
1302
1303
1304
1305
 
# File 'lib/redis.rb', line 1301

def sdiff(*keys)
  synchronize do |client|
    client.call([:sdiff] + keys)
  end
end

#sdiffstore(destination, *keys) ⇒ Fixnum

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

Parameters:

  • destination (String) —

    destination key

  • keys (String, Array<String>) —

    keys pointing to sets to subtract

Returns:

  • (Fixnum) —

    number of elements in the resulting set



1312
1313
1314
1315
1316
 
# File 'lib/redis.rb', line 1312

def sdiffstore(destination, *keys)
  synchronize do |client|
    client.call([:sdiffstore, destination] + keys)
  end
end

#select(db) ⇒ String

Change the selected database for the current connection.

Parameters:

  • db (Fixnum) —

    zero-based index of the DB to use (0 to 15)

Returns:

  • (String) —

    OK



71
72
73
74
75
76
 
# File 'lib/redis.rb', line 71

def select(db)
  synchronize do |client|
    client.db = db
    client.call([:select, db])
  end
end

#set(key, value, options = {}) ⇒ String, Boolean Also known as: []=

Set the string value of a key.

Parameters:

  • key (String)
  • value (String)
  • options (Hash) (defaults to: {}) —
    • :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.

Returns:

  • (String, Boolean) —

    "OK" or true, false if :nx => true or :xx => true



656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
 
# File 'lib/redis.rb', line 656

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

#setbit(key, offset, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • offset (Fixnum) —

    bit offset

  • value (Fixnum) —

    bit value 0 or 1

Returns:

  • (Fixnum) —

    the original bit value stored at offset



856
857
858
859
860
 
# File 'lib/redis.rb', line 856

def setbit(key, offset, value)
  synchronize do |client|
    client.call([:setbit, key, offset, value])
  end
end

#setex(key, ttl, value) ⇒ Object

Set the time to live in seconds of a key.

Parameters:

  • key (String)
  • ttl (Fixnum)
  • value (String) 


688
689
690
691
692
 
# File 'lib/redis.rb', line 688

def setex(key, ttl, value)
  synchronize do |client|
    client.call([:setex, key, ttl, value.to_s])
  end
end

#setnx(key, value) ⇒ Boolean

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

Parameters:

  • key (String)
  • value (String)

Returns:

  • (Boolean) —

    whether the key was set or not



711
712
713
714
715
 
# File 'lib/redis.rb', line 711

def setnx(key, value)
  synchronize do |client|
    client.call([:setnx, key, value.to_s], &_boolify)
  end
end

#setrange(key, offset, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • offset (Fixnum) —

    byte offset

  • value (String)

Returns:

  • (Fixnum) —

    length of the string after it was modified



831
832
833
834
835
 
# File 'lib/redis.rb', line 831

def setrange(key, offset, value)
  synchronize do |client|
    client.call([:setrange, key, offset, value.to_s])
  end
end

#shutdown ⇒ Object

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



236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/redis.rb', line 236

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

#sinter(*keys) ⇒ Array<String>

Intersect multiple sets.

Parameters:

  • keys (String, Array<String>) —

    keys pointing to sets to intersect

Returns:

  • (Array<String>) —

    members in the intersection



1322
1323
1324
1325
1326
 
# File 'lib/redis.rb', line 1322

def sinter(*keys)
  synchronize do |client|
    client.call([:sinter] + keys)
  end
end

#sinterstore(destination, *keys) ⇒ Fixnum

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

Parameters:

  • destination (String) —

    destination key

  • keys (String, Array<String>) —

    keys pointing to sets to intersect

Returns:

  • (Fixnum) —

    number of elements in the resulting set



1333
1334
1335
1336
1337
 
# File 'lib/redis.rb', line 1333

def sinterstore(destination, *keys)
  synchronize do |client|
    client.call([:sinterstore, destination] + keys)
  end
end

#sismember(key, member) ⇒ Boolean

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

Parameters:

  • key (String)
  • member (String)

Returns:

  • (Boolean) 


1281
1282
1283
1284
1285
 
# File 'lib/redis.rb', line 1281

def sismember(key, member)
  synchronize do |client|
    client.call([:sismember, key, member], &_boolify)
  end
end

#slaveof(host, port) ⇒ Object

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



250
251
252
253
254
 
# File 'lib/redis.rb', line 250

def slaveof(host, port)
  synchronize do |client|
    client.call([:slaveof, host, port])
  end
end

#slowlog(subcommand, length = nil) ⇒ Array<String>, ...

Interact with the slowlog (get, len, reset)

Parameters:

  • subcommand (String) —

    e.g. get, len, reset

  • length (Fixnum) (defaults to: nil) —

    maximum number of entries to return

Returns:

  • (Array<String>, Fixnum, String) —

    depends on subcommand



261
262
263
264
265
266
267
 
# File 'lib/redis.rb', line 261

def slowlog(subcommand, length=nil)
  synchronize do |client|
    args = [:slowlog, subcommand]
    args << length if length
    client.call args
  end
end

#smembers(key) ⇒ Array<String>

Get all the members in a set.

Parameters:

  • key (String)

Returns:

  • (Array<String>) 


1291
1292
1293
1294
1295
 
# File 'lib/redis.rb', line 1291

def smembers(key)
  synchronize do |client|
    client.call([:smembers, key])
  end
end

#smove(source, destination, member) ⇒ Boolean

Move a member from one set to another.

Parameters:

  • source (String) —

    source key

  • destination (String) —

    destination key

  • member (String) —

    member to move from source to destination

Returns:

  • (Boolean) 


1270
1271
1272
1273
1274
 
# File 'lib/redis.rb', line 1270

def smove(source, destination, member)
  synchronize do |client|
    client.call([:smove, source, destination, member], &_boolify)
  end
end

#sort(key, options = {}) ⇒ Array<String>, ...

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

Examples:

Retrieve the first 2 elements from an alphabetically sorted "list"

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

Store an alphabetically descending list in "target"

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

Parameters:

  • key (String)
  • options (Hash) (defaults to: {}) —
    • :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

Returns:

  • (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


532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
 
# File 'lib/redis.rb', line 532

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

#spop(key) ⇒ String

Remove and return a random member from a set.

Parameters:

  • key (String)

Returns:

  • (String) 


1243
1244
1245
1246
1247
 
# File 'lib/redis.rb', line 1243

def spop(key)
  synchronize do |client|
    client.call([:spop, key])
  end
end

#srandmember(key, count = nil) ⇒ String

Get one or more random members from a set.

Parameters:

  • key (String)
  • count (Fixnum) (defaults to: nil)

Returns:

  • (String) 


1254
1255
1256
1257
1258
1259
1260
1261
1262
 
# File 'lib/redis.rb', line 1254

def srandmember(key, count = nil)
  synchronize do |client|
    if count.nil?
      client.call([:srandmember, key])
    else
      client.call([:srandmember, key, count])
    end
  end
end

#srem(key, member) ⇒ Boolean, Fixnum

Remove one or more members from a set.

Parameters:

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

    one member, or array of members

Returns:

  • (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



1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
 
# File 'lib/redis.rb', line 1225

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

#sscan(key, cursor, options = {}) ⇒ String+

Scan a set

Examples:

Retrieve the first batch of keys in a set

redis.sscan("set", 0)

Parameters:

  • cursor: (String, Integer) —

    the cursor of the iteration

  • options (Hash) (defaults to: {}) —
    • :match => String: only return keys matching the pattern
    • :count => Integer: return count keys at most per iteration

Returns:

  • (String, Array<String>) —

    the next cursor and all found members



2392
2393
2394
 
# File 'lib/redis.rb', line 2392

def sscan(key, cursor, options={})
  _scan(:sscan, cursor, [key], options)
end

#sscan_each(key, options = {}, &block) ⇒ Enumerator

Scan a set

Examples:

Retrieve all of the keys in a set

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

Parameters:

  • options (Hash) (defaults to: {}) —
    • :match => String: only return keys matching the pattern
    • :count => Integer: return count keys at most per iteration

Returns:

  • (Enumerator) —

    an enumerator for all keys in the set



2407
2408
2409
2410
2411
2412
2413
2414
2415
 
# File 'lib/redis.rb', line 2407

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

#strlen(key) ⇒ Fixnum

Get the length of the value stored in a key.

Parameters:

  • key (String)

Returns:

  • (Fixnum) —

    the length of the value stored in the key, or 0 if the key does not exist



925
926
927
928
929
 
# File 'lib/redis.rb', line 925

def strlen(key)
  synchronize do |client|
    client.call([:strlen, key])
  end
end

#subscribe(*channels, &block) ⇒ Object

Listen for messages published to the given channels.



1952
1953
1954
1955
1956
 
# File 'lib/redis.rb', line 1952

def subscribe(*channels, &block)
  synchronize do |client|
    _subscription(:subscribe, channels, block)
  end
end

#subscribed? ⇒ Boolean

Returns:

  • (Boolean) 


1945
1946
1947
1948
1949
 
# File 'lib/redis.rb', line 1945

def subscribed?
  synchronize do |client|
    client.kind_of? SubscribedClient
  end
end

#sunion(*keys) ⇒ Array<String>

Add multiple sets.

Parameters:

  • keys (String, Array<String>) —

    keys pointing to sets to unify

Returns:

  • (Array<String>) —

    members in the union



1343
1344
1345
1346
1347
 
# File 'lib/redis.rb', line 1343

def sunion(*keys)
  synchronize do |client|
    client.call([:sunion] + keys)
  end
end

#sunionstore(destination, *keys) ⇒ Fixnum

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

Parameters:

  • destination (String) —

    destination key

  • keys (String, Array<String>) —

    keys pointing to sets to unify

Returns:

  • (Fixnum) —

    number of elements in the resulting set



1354
1355
1356
1357
1358
 
# File 'lib/redis.rb', line 1354

def sunionstore(destination, *keys)
  synchronize do |client|
    client.call([:sunionstore, destination] + keys)
  end
end

#sync ⇒ Object

Internal command used for replication.



270
271
272
273
274
 
# File 'lib/redis.rb', line 270

def sync
  synchronize do |client|
    client.call([:sync])
  end
end

#synchronize ⇒ Object 



35
36
37
 
# File 'lib/redis.rb', line 35

def synchronize
  mon_synchronize { yield(@client) }
end

#time ⇒ Array<Fixnum>

Return the server time.

Examples:

r.time # => [ 1333093196, 606806 ]

Returns:

  • (Array<Fixnum>) —

    tuple of seconds since UNIX epoch and microseconds in the current second



283
284
285
286
287
288
289
 
# File 'lib/redis.rb', line 283

def time
  synchronize do |client|
    client.call([:time]) do |reply|
      reply.map(&:to_i) if reply
    end
  end
end

#ttl(key) ⇒ Fixnum

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

Parameters:

  • key (String)

Returns:

  • (Fixnum) —

    remaining time to live in seconds, or -1 if the key does not exist or does not have a timeout



328
329
330
331
332
 
# File 'lib/redis.rb', line 328

def ttl(key)
  synchronize do |client|
    client.call([:ttl, key])
  end
end

#type(key) ⇒ String

Determine the type stored at key.

Parameters:

  • key (String)

Returns:

  • (String) —

    string, list, set, zset, hash or none



567
568
569
570
571
 
# File 'lib/redis.rb', line 567

def type(key)
  synchronize do |client|
    client.call([:type, key])
  end
end

#unsubscribe(*channels) ⇒ Object

Stop listening for messages posted to the given channels.



1959
1960
1961
1962
1963
1964
 
# File 'lib/redis.rb', line 1959

def unsubscribe(*channels)
  synchronize do |client|
    raise RuntimeError, "Can't unsubscribe if not subscribed." unless subscribed?
    client.unsubscribe(*channels)
  end
end

#unwatch ⇒ String

Forget about all watched keys.

Returns:

  • (String) —

    OK

See Also:



2036
2037
2038
2039
2040
 
# File 'lib/redis.rb', line 2036

def unwatch
  synchronize do |client|
    client.call([:unwatch])
  end
end

#watch(*keys) ⇒ Object, String

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.

Examples:

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]

Without a block

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

Parameters:

  • keys (String, Array<String>) —

    one or more keys to watch

Returns:

  • (Object) —

    if using a block, returns the return value of the block

  • (String) —

    if not using a block, returns OK

See Also:



2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
 
# File 'lib/redis.rb', line 2011

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

#with_reconnect(val = true, &blk) ⇒ Object

Run code with the client reconnecting



40
41
42
43
44
 
# File 'lib/redis.rb', line 40

def with_reconnect(val=true, &blk)
  synchronize do |client|
    client.with_reconnect(val, &blk)
  end
end

#without_reconnect(&blk) ⇒ Object

Run code without the client reconnecting



47
48
49
 
# File 'lib/redis.rb', line 47

def without_reconnect(&blk)
  with_reconnect(false, &blk)
end

#zadd(key, *args) ⇒ Boolean, Fixnum

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

Parameters:

  • key (String)
  • args ([Float, String], Array<[Float, String]>) —
    • a single [score, member] pair
    • an array of [score, member] pairs

Returns:

  • (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


1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
 
# File 'lib/redis.rb', line 1392

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

#zcard(key) ⇒ Fixnum

Get the number of members in a sorted set.

Examples:

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

Parameters:

  • key (String)

Returns:

  • (Fixnum) 


1368
1369
1370
1371
1372
 
# File 'lib/redis.rb', line 1368

def zcard(key)
  synchronize do |client|
    client.call([:zcard, key])
  end
end

#zcount(key, min, max) ⇒ Fixnum

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

Parameters:

  • key (String)
  • min (String) —
    • inclusive minimum score is specified verbatim
    • exclusive minimum score is specified by prefixing (
  • max (String) —
    • inclusive maximum score is specified verbatim
    • exclusive maximum score is specified by prefixing (

Returns:

  • (Fixnum) —

    number of members in within the specified range



1686
1687
1688
1689
1690
 
# File 'lib/redis.rb', line 1686

def zcount(key, min, max)
  synchronize do |client|
    client.call([:zcount, key, min, max])
  end
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

Parameters:

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

Returns:

  • (Float) —

    score of the member after incrementing it



1416
1417
1418
1419
1420
 
# File 'lib/redis.rb', line 1416

def zincrby(key, increment, member)
  synchronize do |client|
    client.call([:zincrby, key, increment, member], &_floatify)
  end
end

#zinterstore(destination, keys, options = {}) ⇒ Fixnum

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

Parameters:

  • destination (String) —

    destination key

  • keys (Array<String>) —

    source keys

  • options (Hash) (defaults to: {}) —
    • :weights => [Float, Float, ...]: weights to associate with source sorted sets
    • :aggregate => String: aggregate function to use (sum, min, max, ...)

Returns:

  • (Fixnum) —

    number of elements in the resulting sorted set



1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
 
# File 'lib/redis.rb', line 1706

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

#zrange(key, start, stop, options = {}) ⇒ Array<String>, Array<[String, Float]>

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

Examples:

Retrieve all members from a sorted set

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

Parameters:

  • key (String)
  • start (Fixnum) —

    start index

  • stop (Fixnum) —

    stop index

  • options (Hash) (defaults to: {}) —
    • :with_scores => true: include scores in output

Returns:

  • (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


1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
 
# File 'lib/redis.rb', line 1486

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

#zrangebyscore(key, min, max, options = {}) ⇒ 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]]

Parameters:

  • key (String)
  • min (String) —
    • inclusive minimum score is specified verbatim
    • exclusive minimum score is specified by prefixing (
  • max (String) —
    • inclusive maximum score is specified verbatim
    • exclusive maximum score is specified by prefixing (
  • options (Hash) (defaults to: {}) —
    • :with_scores => true: include scores in output
    • :limit => [offset, count]: skip offset members, return a maximum of count members

Returns:

  • (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


1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
 
# File 'lib/redis.rb', line 1596

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

#zrank(key, member) ⇒ Fixnum

Determine the index of a member in a sorted set.

Parameters:

  • key (String)
  • member (String)

Returns:

  • (Fixnum) 


1532
1533
1534
1535
1536
 
# File 'lib/redis.rb', line 1532

def zrank(key, member)
  synchronize do |client|
    client.call([:zrank, key, member])
  end
end

#zrem(key, member) ⇒ Boolean, Fixnum

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

Parameters:

  • key (String)
  • member (String, Array<String>) —
    • a single member
    • an array of members

Returns:

  • (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


1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
 
# File 'lib/redis.rb', line 1439

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

#zremrangebyrank(key, start, stop) ⇒ Fixnum

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

Parameters:

  • key (String)
  • start (Fixnum) —

    start index

  • stop (Fixnum) —

    stop index

Returns:

  • (Fixnum) —

    number of members that were removed



1563
1564
1565
1566
1567
 
# File 'lib/redis.rb', line 1563

def zremrangebyrank(key, start, stop)
  synchronize do |client|
    client.call([:zremrangebyrank, key, start, stop])
  end
end

#zremrangebyscore(key, min, max) ⇒ Fixnum

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

Parameters:

  • key (String)
  • min (String) —
    • inclusive minimum score is specified verbatim
    • exclusive minimum score is specified by prefixing (
  • max (String) —
    • inclusive maximum score is specified verbatim
    • exclusive maximum score is specified by prefixing (

Returns:

  • (Fixnum) —

    number of members that were removed



1663
1664
1665
1666
1667
 
# File 'lib/redis.rb', line 1663

def zremrangebyscore(key, min, max)
  synchronize do |client|
    client.call([:zremrangebyscore, key, min, max])
  end
end

#zrevrange(key, start, stop, options = {}) ⇒ 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:



1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
 
# File 'lib/redis.rb', line 1512

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

#zrevrangebyscore(key, max, min, options = {}) ⇒ 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:



1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
 
# File 'lib/redis.rb', line 1628

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

#zrevrank(key, member) ⇒ Fixnum

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

Parameters:

  • key (String)
  • member (String)

Returns:

  • (Fixnum) 


1544
1545
1546
1547
1548
 
# File 'lib/redis.rb', line 1544

def zrevrank(key, member)
  synchronize do |client|
    client.call([:zrevrank, key, member])
  end
end

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

Scan a sorted set

Examples:

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

redis.zscan("zset", 0)

Parameters:

  • cursor: (String, Integer) —

    the cursor of the iteration

  • options (Hash) (defaults to: {}) —
    • :match => String: only return keys matching the pattern
    • :count => Integer: return count keys at most per iteration

Returns:

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

    the next cursor and all found members and scores



2354
2355
2356
2357
2358
 
# File 'lib/redis.rb', line 2354

def zscan(key, cursor, options={})
  _scan(:zscan, cursor, [key], options) do |reply|
    [reply[0], _floatify_pairs.call(reply[1])]
  end
end

#zscan_each(key, options = {}, &block) ⇒ Enumerator

Scan a sorted set

Examples:

Retrieve all of the members/scores in a sorted set

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

Parameters:

  • options (Hash) (defaults to: {}) —
    • :match => String: only return keys matching the pattern
    • :count => Integer: return count keys at most per iteration

Returns:

  • (Enumerator) —

    an enumerator for all found scores and members



2371
2372
2373
2374
2375
2376
2377
2378
2379
 
# File 'lib/redis.rb', line 2371

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

Parameters:

  • key (String)
  • member (String)

Returns:

  • (Float) —

    score of the member



1462
1463
1464
1465
1466
 
# File 'lib/redis.rb', line 1462

def zscore(key, member)
  synchronize do |client|
    client.call([:zscore, key, member], &_floatify)
  end
end

#zunionstore(destination, keys, options = {}) ⇒ Fixnum

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

Parameters:

  • destination (String) —

    destination key

  • keys (Array<String>) —

    source keys

  • options (Hash) (defaults to: {}) —
    • :weights => [Float, Float, ...]: weights to associate with source sorted sets
    • :aggregate => String: aggregate function to use (sum, min, max, ...)

Returns:

  • (Fixnum) —

    number of elements in the resulting sorted set



1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
 
# File 'lib/redis.rb', line 1733

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