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.3.5"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Redis

Create a new client instance

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :url (String) — default: value of the environment variable REDIS_URL —

    a Redis URL, for a TCP connection: redis://:[password]@[hostname]:[port]/[db] (password, port and database are optional), for a unix socket connection: unix://[path to Redis socket]. This overrides all other options.

  • :host (String) — default: "127.0.0.1" —

    server hostname

  • :port (Fixnum) — default: 6379 —

    server port

  • :path (String) —

    path to server socket (overrides host and port)

  • :timeout (Float) — default: 5.0 —

    timeout in seconds

  • :connect_timeout (Float) — default: same as timeout —

    timeout for initial connect in seconds

  • :password (String) —

    Password to authenticate against server

  • :db (Fixnum) — default: 0 —

    Database to select after initial connect

  • :driver (Symbol) —

    Driver to use, currently supported: :ruby, :hiredis, :synchrony

  • :id (String) —

    ID for the client connection, assigns name to current connection by sending CLIENT SETNAME

  • :tcp_keepalive (Hash, Fixnum) —

    Keepalive values, if Fixnum intvl and probe are calculated based on the value, if Hash time, intvl and probes can be specified as a Fixnum

  • :reconnect_attempts (Fixnum) —

    Number of attempts trying to connect

  • :inherit_socket (Boolean) — default: false —

    Whether to use socket in forked process or not

  • :sentinels (Array) —

    List of sentinels to contact

  • :role (Symbol) — default: :master —

    Role to fetch via Sentinel, either :master or :slave



49
50
51
52
53
54
55
 
# File 'lib/redis.rb', line 49

def initialize(options = {})
  @options = options.dup
  @original_client = @client = Client.new(options)
  @queue = Hash.new { |h, k| h[k] = [] }

  super() # Monitor#initialize
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(command, *args) ⇒ Object 



2713
2714
2715
2716
2717
 
# File 'lib/redis.rb', line 2713

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 



1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
 
# File 'lib/redis.rb', line 1116

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 



2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
 
# File 'lib/redis.rb', line 2390

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 



2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
 
# File 'lib/redis.rb', line 2453

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



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

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



127
128
129
130
131
 
# File 'lib/redis.rb', line 127

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

#bgrewriteaof ⇒ String

Asynchronously rewrite the append-only file.

Returns:

  • (String) —

    OK



180
181
182
183
184
 
# File 'lib/redis.rb', line 180

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

#bgsave ⇒ String

Asynchronously save the dataset to disk.

Returns:

  • (String) —

    OK



189
190
191
192
193
 
# File 'lib/redis.rb', line 189

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



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

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



981
982
983
984
985
 
# File 'lib/redis.rb', line 981

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

#bitpos(key, bit, start = nil, stop = nil) ⇒ Fixnum

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

Parameters:

  • key (String)
  • bit (Fixnum) —

    whether to look for the first 1 or 0 bit

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

    start index

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

    stop index

Returns:

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



995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
 
# File 'lib/redis.rb', line 995

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

#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


1162
1163
1164
 
# File 'lib/redis.rb', line 1162

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:



1178
1179
1180
 
# File 'lib/redis.rb', line 1178

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


1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
 
# File 'lib/redis.rb', line 1193

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

#call(*command) ⇒ Object

Sends a command to Redis and returns its reply.

Replies are converted to Ruby objects according to the RESP protocol, so you can expect a Ruby array, integer or nil when Redis sends one. Higher level transformations, such as converting an array of pairs into a Ruby hash, are up to consumers.

Redis error replies are raised as Ruby exceptions.



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

def call(*command)
  synchronize do |client|
    client.call(command)
  end
end

#close ⇒ Object Also known as: disconnect!

Disconnect the client as quickly and silently as possible.



79
80
81
 
# File 'lib/redis.rb', line 79

def close
  @original_client.disconnect
end

#commit ⇒ Object

Sends all commands in the queue.

See http://redis.io/topics/pipelining for more details.



112
113
114
115
116
117
118
119
120
 
# File 'lib/redis.rb', line 112

def commit
  synchronize do |client|
    begin
      client.call_pipelined(@queue[Thread.current.object_id])
    ensure
      @queue.delete(Thread.current.object_id)
    end
  end
end

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

Get or set server configuration parameters.

Parameters:

  • action (Symbol) —

    e.g. :get, :set, :resetstat

Returns:

  • (String, Hash) —

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



200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/redis.rb', line 200

def config(action, *args)
  synchronize do |client|
    client.call([:config, action] + args) do |reply|
      if reply.kind_of?(Array) && action == :get
        Hashify.call(reply)
      else
        reply
      end
    end
  end
end

#connected? ⇒ Boolean

Test whether or not the client is connected

Returns:

  • (Boolean) 


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

def connected?
  @original_client.connected?
end

#connection ⇒ Object 



2703
2704
2705
2706
2707
2708
2709
2710
2711
 
# File 'lib/redis.rb', line 2703

def connection
  {
    :host     => @original_client.host,
    :port     => @original_client.port,
    :db       => @original_client.db,
    :id       => @original_client.id,
    :location => @original_client.location
  }
end

#dbsize ⇒ Fixnum

Return the number of keys in the selected database.

Returns:

  • (Fixnum) 


215
216
217
218
219
 
# File 'lib/redis.rb', line 215

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

#debug(*args) ⇒ Object 



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

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



660
661
662
663
664
 
# File 'lib/redis.rb', line 660

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



675
676
677
678
679
 
# File 'lib/redis.rb', line 675

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



492
493
494
495
496
 
# File 'lib/redis.rb', line 492

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

#discard ⇒ String

Discard all commands issued after MULTI.

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

Returns:

  • (String) —

    "OK"

See Also:



2336
2337
2338
2339
2340
 
# File 'lib/redis.rb', line 2336

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



450
451
452
453
454
 
# File 'lib/redis.rb', line 450

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

#dup ⇒ Object 



2699
2700
2701
 
# File 'lib/redis.rb', line 2699

def dup
  self.class.new(@options)
end

#echo(value) ⇒ String

Echo the given string.

Parameters:

  • value (String)

Returns:

  • (String) 


157
158
159
160
161
 
# File 'lib/redis.rb', line 157

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:



2424
2425
2426
 
# File 'lib/redis.rb', line 2424

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:



2449
2450
2451
 
# File 'lib/redis.rb', line 2449

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:



2322
2323
2324
2325
2326
 
# File 'lib/redis.rb', line 2322

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

#exists(key) ⇒ Boolean

Determine if a key exists.

Parameters:

  • key (String)

Returns:

  • (Boolean) 


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

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



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

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



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

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



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

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

#flushdb ⇒ String

Remove all keys from the current database.

Returns:

  • (String) —

    OK



239
240
241
242
243
 
# File 'lib/redis.rb', line 239

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) 


860
861
862
863
864
 
# File 'lib/redis.rb', line 860

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



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

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



923
924
925
926
927
 
# File 'lib/redis.rb', line 923

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



1014
1015
1016
1017
1018
 
# File 'lib/redis.rb', line 1014

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



2056
2057
2058
2059
2060
 
# File 'lib/redis.rb', line 2056

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



2067
2068
2069
2070
2071
 
# File 'lib/redis.rb', line 2067

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) 


2007
2008
2009
2010
2011
 
# File 'lib/redis.rb', line 2007

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


2121
2122
2123
2124
2125
 
# File 'lib/redis.rb', line 2121

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



2079
2080
2081
2082
2083
 
# File 'lib/redis.rb', line 2079

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



2091
2092
2093
2094
2095
 
# File 'lib/redis.rb', line 2091

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


2101
2102
2103
2104
2105
 
# File 'lib/redis.rb', line 2101

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



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

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:



2024
2025
2026
2027
2028
 
# File 'lib/redis.rb', line 2024

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

#hmset(key, *attrs) ⇒ String

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

Returns:

  • (String) —

    "OK"

See Also:



1981
1982
1983
1984
1985
 
# File 'lib/redis.rb', line 1981

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



2526
2527
2528
2529
2530
 
# File 'lib/redis.rb', line 2526

def hscan(key, cursor, options={})
  _scan(:hscan, cursor, [key], options) do |reply|
    [reply[0], reply[1].each_slice(2).to_a]
  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



2543
2544
2545
2546
2547
2548
2549
2550
2551
 
# File 'lib/redis.rb', line 2543

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



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

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



1964
1965
1966
1967
1968
 
# File 'lib/redis.rb', line 1964

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


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

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

#id ⇒ Object 



2691
2692
2693
 
# File 'lib/redis.rb', line 2691

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



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

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



704
705
706
707
708
 
# File 'lib/redis.rb', line 704

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



719
720
721
722
723
 
# File 'lib/redis.rb', line 719

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


249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/redis.rb', line 249

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 



2695
2696
2697
 
# File 'lib/redis.rb', line 2695

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


512
513
514
515
516
517
518
519
520
521
522
 
# File 'lib/redis.rb', line 512

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) 


274
275
276
277
278
 
# File 'lib/redis.rb', line 274

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) 


1214
1215
1216
1217
1218
 
# File 'lib/redis.rb', line 1214

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



1228
1229
1230
1231
1232
 
# File 'lib/redis.rb', line 1228

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) 


1035
1036
1037
1038
1039
 
# File 'lib/redis.rb', line 1035

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) 


1089
1090
1091
1092
1093
 
# File 'lib/redis.rb', line 1089

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)
  • value (String, Array) —

    string value, or array of string values to push

Returns:

  • (Fixnum) —

    the length of the list after the push operation



1046
1047
1048
1049
1050
 
# File 'lib/redis.rb', line 1046

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



1057
1058
1059
1060
1061
 
# File 'lib/redis.rb', line 1057

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


1240
1241
1242
1243
1244
 
# File 'lib/redis.rb', line 1240

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



1255
1256
1257
1258
1259
 
# File 'lib/redis.rb', line 1255

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



1267
1268
1269
1270
1271
 
# File 'lib/redis.rb', line 1267

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



1279
1280
1281
1282
1283
 
# File 'lib/redis.rb', line 1279

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.mapped_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:



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

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) ⇒ String

Set one or more hash values.

Examples:

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

Parameters:

  • key (String)
  • hash (Hash) —

    a non-empty hash with fields mapping to values

Returns:

  • (String) —

    "OK"

See Also:



1998
1999
2000
 
# File 'lib/redis.rb', line 1998

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", "key2")
  # => { "key1" => "v1", "key2" => "v2" }

Parameters:

  • keys (Array<String>) —

    array of keys

Returns:

  • (Hash) —

    a hash mapping the specified keys to their values

See Also:



894
895
896
897
898
899
900
901
902
 
# File 'lib/redis.rb', line 894

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) ⇒ String

Set one or more values.

Examples:

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

Parameters:

  • hash (Hash) —

    keys mapping to values

Returns:

  • (String) —

    "OK"

See Also:



822
823
824
 
# File 'lib/redis.rb', line 822

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.mapped_msetnx({ "key1" => "v1", "key2" => "v2" })
  # => true

Parameters:

  • hash (Hash) —

    keys mapping to values

Returns:

  • (Boolean) —

    whether or not all values were set

See Also:



852
853
854
 
# File 'lib/redis.rb', line 852

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:



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

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"



477
478
479
480
481
482
483
484
485
486
 
# File 'lib/redis.rb', line 477

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



286
287
288
289
290
 
# File 'lib/redis.rb', line 286

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



543
544
545
546
547
 
# File 'lib/redis.rb', line 543

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

#mset(*args) ⇒ String

Set one or more values.

Examples:

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

Parameters:

  • args (Array<String>) —

    array of keys and values

Returns:

  • (String) —

    "OK"

See Also:



806
807
808
809
810
 
# File 'lib/redis.rb', line 806

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:



836
837
838
839
840
 
# File 'lib/redis.rb', line 836

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:



2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
 
# File 'lib/redis.rb', line 2295

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 



549
550
551
552
553
 
# File 'lib/redis.rb', line 549

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



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

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



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

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



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

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

#pfadd(key, member) ⇒ Boolean

Add one or more members to a HyperLogLog structure.

Parameters:

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

    one member, or array of members

Returns:

  • (Boolean) —

    true if at least 1 HyperLogLog internal register was altered. false otherwise.



2633
2634
2635
2636
2637
 
# File 'lib/redis.rb', line 2633

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

#pfcount(*keys) ⇒ Fixnum

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.

Parameters:

  • keys (String, Array<String>)

Returns:

  • (Fixnum) 


2646
2647
2648
2649
2650
 
# File 'lib/redis.rb', line 2646

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

#pfmerge(dest_key, *source_key) ⇒ Boolean

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.

Parameters:

  • dest_key (String) —

    destination key

  • source_key (String, Array<String>) —

    source key, or array of keys

Returns:

  • (Boolean) 


2658
2659
2660
2661
2662
 
# File 'lib/redis.rb', line 2658

def pfmerge(dest_key, *source_key)
  synchronize do |client|
    client.call([:pfmerge, dest_key, *source_key], &BoolifySet)
  end
end

#ping ⇒ String

Ping the server.

Returns:

  • (String) —

    PONG



147
148
149
150
151
 
# File 'lib/redis.rb', line 147

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

#pipelined ⇒ Object 



2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
 
# File 'lib/redis.rb', line 2253

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) ⇒ String

Set the time to live in milliseconds of a key.

Parameters:

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

Returns:

  • (String) —

    "OK"



779
780
781
782
783
 
# File 'lib/redis.rb', line 779

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.



2163
2164
2165
2166
2167
 
# File 'lib/redis.rb', line 2163

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

#psubscribe_with_timeout(timeout, *channels, &block) ⇒ Object

Listen for messages published to channels matching the given patterns. Throw a timeout error if there is no messages for a timeout period.



2170
2171
2172
2173
2174
 
# File 'lib/redis.rb', line 2170

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

#pttl(key) ⇒ Fixnum

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

In Redis 2.6 or older the command returns -1 if the key does not exist or if the key exist but has no associated expire.

Starting with Redis 2.8 the return value in case of error changed:

- The command returns -2 if the key does not exist.
- The command returns -1 if the key exists but has no associated expire.

Parameters:

  • key (String)

Returns:

  • (Fixnum) —

    remaining time to live in milliseconds



440
441
442
443
444
 
# File 'lib/redis.rb', line 440

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

#publish(channel, message) ⇒ Object

Post a message to a channel.



2128
2129
2130
2131
2132
 
# File 'lib/redis.rb', line 2128

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

#pubsub(subcommand, *args) ⇒ Object

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



2186
2187
2188
2189
2190
 
# File 'lib/redis.rb', line 2186

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

#punsubscribe(*channels) ⇒ Object

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



2177
2178
2179
2180
2181
2182
 
# File 'lib/redis.rb', line 2177

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

#queue(*command) ⇒ Object

Queues a command for pipelining.

Commands in the queue are executed with the Redis#commit method.

See http://redis.io/topics/pipelining for more details.



104
105
106
 
# File 'lib/redis.rb', line 104

def queue(*command)
  @queue[Thread.current.object_id] << command
end

#quit ⇒ String

Close the connection.

Returns:

  • (String) —

    OK



166
167
168
169
170
171
172
173
174
175
 
# File 'lib/redis.rb', line 166

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) 


558
559
560
561
562
 
# File 'lib/redis.rb', line 558

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



569
570
571
572
573
 
# File 'lib/redis.rb', line 569

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



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

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

#restore(key, ttl, serialized_value) ⇒ String

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

Parameters:

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

Returns:

  • (String) —

    "OK"



462
463
464
465
466
 
# File 'lib/redis.rb', line 462

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) 


1099
1100
1101
1102
1103
 
# File 'lib/redis.rb', line 1099

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



1110
1111
1112
1113
1114
 
# File 'lib/redis.rb', line 1110

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



1068
1069
1070
1071
1072
 
# File 'lib/redis.rb', line 1068

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



1079
1080
1081
1082
1083
 
# File 'lib/redis.rb', line 1079

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



1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
 
# File 'lib/redis.rb', line 1303

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) 


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

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



2486
2487
2488
 
# File 'lib/redis.rb', line 2486

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



2505
2506
2507
2508
2509
2510
2511
2512
2513
 
# File 'lib/redis.rb', line 2505

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) 


1289
1290
1291
1292
1293
 
# File 'lib/redis.rb', line 1289

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:



2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
 
# File 'lib/redis.rb', line 2366

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



1406
1407
1408
1409
1410
 
# File 'lib/redis.rb', line 1406

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



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

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



137
138
139
140
141
142
 
# File 'lib/redis.rb', line 137

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

#sentinel(subcommand, *args) ⇒ Array<String>, ...

Interact with the sentinel command (masters, master, slaves, failover)

Parameters:

  • subcommand (String) —

    e.g. masters, master, slaves

  • args (Array<String>) —

    depends on subcommand

Returns:

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

    depends on subcommand



2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
 
# File 'lib/redis.rb', line 2669

def sentinel(subcommand, *args)
  subcommand = subcommand.to_s.downcase
  synchronize do |client|
    client.call([:sentinel, subcommand] + args) do |reply|
      case subcommand
      when "get-master-addr-by-name"
        reply
      else
        if reply.kind_of?(Array)
          if reply[0].kind_of?(Array)
            reply.map(&Hashify)
          else
            Hashify.call(reply)
          end
        else
          reply
        end
      end
    end
  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



735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
 
# File 'lib/redis.rb', line 735

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, &BoolifySet)
    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



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

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

#setex(key, ttl, value) ⇒ String

Set the time to live in seconds of a key.

Parameters:

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

Returns:

  • (String) —

    "OK"



767
768
769
770
771
 
# File 'lib/redis.rb', line 767

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



790
791
792
793
794
 
# File 'lib/redis.rb', line 790

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



910
911
912
913
914
 
# File 'lib/redis.rb', line 910

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.



302
303
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/redis.rb', line 302

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



1427
1428
1429
1430
1431
 
# File 'lib/redis.rb', line 1427

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



1438
1439
1440
1441
1442
 
# File 'lib/redis.rb', line 1438

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) 


1386
1387
1388
1389
1390
 
# File 'lib/redis.rb', line 1386

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.



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

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



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

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


1396
1397
1398
1399
1400
 
# File 'lib/redis.rb', line 1396

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) 


1375
1376
1377
1378
1379
 
# File 'lib/redis.rb', line 1375

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


611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
 
# File 'lib/redis.rb', line 611

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, count = nil) ⇒ String

Remove and return one or more random member from a set.

Parameters:

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

Returns:

  • (String) 


1344
1345
1346
1347
1348
1349
1350
1351
1352
 
# File 'lib/redis.rb', line 1344

def spop(key, count = nil)
  synchronize do |client|
    if count.nil?
      client.call([:spop, key])
    else
      client.call([:spop, key, count])
    end
  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) 


1359
1360
1361
1362
1363
1364
1365
1366
1367
 
# File 'lib/redis.rb', line 1359

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



1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
 
# File 'lib/redis.rb', line 1325

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



2603
2604
2605
 
# File 'lib/redis.rb', line 2603

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_each("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



2618
2619
2620
2621
2622
2623
2624
2625
2626
 
# File 'lib/redis.rb', line 2618

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



1025
1026
1027
1028
1029
 
# File 'lib/redis.rb', line 1025

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

#subscribe(*channels, &block) ⇒ Object

Listen for messages published to the given channels.



2141
2142
2143
2144
2145
 
# File 'lib/redis.rb', line 2141

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

#subscribe_with_timeout(timeout, *channels, &block) ⇒ Object

Listen for messages published to the given channels. Throw a timeout error if there is no messages for a timeout period.



2148
2149
2150
2151
2152
 
# File 'lib/redis.rb', line 2148

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

#subscribed? ⇒ Boolean

Returns:

  • (Boolean) 


2134
2135
2136
2137
2138
 
# File 'lib/redis.rb', line 2134

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



1448
1449
1450
1451
1452
 
# File 'lib/redis.rb', line 1448

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



1459
1460
1461
1462
1463
 
# File 'lib/redis.rb', line 1459

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

#sync ⇒ Object

Internal command used for replication.



336
337
338
339
340
 
# File 'lib/redis.rb', line 336

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

#synchronize ⇒ Object 



57
58
59
 
# File 'lib/redis.rb', line 57

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



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

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.

In Redis 2.6 or older the command returns -1 if the key does not exist or if the key exist but has no associated expire.

Starting with Redis 2.8 the return value in case of error changed:

- The command returns -2 if the key does not exist.
- The command returns -1 if the key exists but has no associated expire.

Parameters:

  • key (String)

Returns:

  • (Fixnum) —

    remaining time to live in seconds.



401
402
403
404
405
 
# File 'lib/redis.rb', line 401

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



646
647
648
649
650
 
# File 'lib/redis.rb', line 646

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

#unsubscribe(*channels) ⇒ Object

Stop listening for messages posted to the given channels.



2155
2156
2157
2158
2159
2160
 
# File 'lib/redis.rb', line 2155

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:



2247
2248
2249
2250
2251
 
# File 'lib/redis.rb', line 2247

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:



2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
 
# File 'lib/redis.rb', line 2222

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



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

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



69
70
71
 
# File 'lib/redis.rb', line 69

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

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

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

Examples:

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

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

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

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

Parameters:

  • key (String)
  • args ([Float, String], Array<[Float, String]>) —
    • a single [score, member] pair
    • an array of [score, member] pairs
  • options (Hash) —
    • :xx => true: Only update elements that already exist (never add elements)
    • :nx => true: Don't update already existing elements (always add new elements)
    • :ch => true: Modify the return value from the number of new elements added, to the total number of elements changed (CH is an abbreviation of changed); changed elements are new elements added and elements already existing for which the score was updated
    • :incr => true: When this option is specified ZADD acts like ZINCRBY; only one score-element pair can be specified in this mode

Returns:

  • (Boolean, Fixnum, Float) —
    • 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.
    • Float when option :incr is specified, holding the score of the member after incrementing it.


1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
 
# File 'lib/redis.rb', line 1510

def zadd(key, *args) #, options
  zadd_options = []
  if args.last.is_a?(Hash)
    options = args.pop

    nx = options[:nx]
    zadd_options << "NX" if nx

    xx = options[:xx]
    zadd_options << "XX" if xx

    ch = options[:ch]
    zadd_options << "CH" if ch

    incr = options[:incr]
    zadd_options << "INCR" if incr
  end

  synchronize do |client|
    if args.size == 1 && args[0].is_a?(Array)
      # Variadic: return float if INCR, integer if !INCR
      client.call([:zadd, key] + zadd_options + args[0], &(incr ? Floatify : nil))
    elsif args.size == 2
      # Single pair: return float if INCR, boolean if !INCR
      client.call([:zadd, key] + zadd_options + args, &(incr ? Floatify : 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) 


1473
1474
1475
1476
1477
 
# File 'lib/redis.rb', line 1473

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



1875
1876
1877
1878
1879
 
# File 'lib/redis.rb', line 1875

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



1551
1552
1553
1554
1555
 
# File 'lib/redis.rb', line 1551

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



1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
 
# File 'lib/redis.rb', line 1895

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


1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
 
# File 'lib/redis.rb', line 1621

def zrange(key, start, stop, options = {})
  args = []

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

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

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

#zrangebylex(key, min, max, options = {}) ⇒ Array<String>, Array<[String, Float]>

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

Examples:

Retrieve members matching a

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

Retrieve the first 2 members matching a

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

Parameters:

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

Returns:

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


1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
 
# File 'lib/redis.rb', line 1725

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

#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


1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
 
# File 'lib/redis.rb', line 1785

def zrangebyscore(key, min, max, options = {})
  args = []

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

  if with_scores
    args << "WITHSCORES"
    block = FloatifyPairs
  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) 


1667
1668
1669
1670
1671
 
# File 'lib/redis.rb', line 1667

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


1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
 
# File 'lib/redis.rb', line 1574

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



1698
1699
1700
1701
1702
 
# File 'lib/redis.rb', line 1698

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



1852
1853
1854
1855
1856
 
# File 'lib/redis.rb', line 1852

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:



1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
 
# File 'lib/redis.rb', line 1647

def zrevrange(key, start, stop, options = {})
  args = []

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

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

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

#zrevrangebylex(key, max, min, options = {}) ⇒ Object

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

Examples:

Retrieve members matching a

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

Retrieve the last 2 members matching a

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

See Also:



1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
 
# File 'lib/redis.rb', line 1747

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

#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:



1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
 
# File 'lib/redis.rb', line 1817

def zrevrangebyscore(key, max, min, options = {})
  args = []

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

  if with_scores
    args << ["WITHSCORES"]
    block = FloatifyPairs
  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) 


1679
1680
1681
1682
1683
 
# File 'lib/redis.rb', line 1679

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



2565
2566
2567
2568
2569
 
# File 'lib/redis.rb', line 2565

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

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

Scan a sorted set

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



2582
2583
2584
2585
2586
2587
2588
2589
2590
 
# File 'lib/redis.rb', line 2582

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



1597
1598
1599
1600
1601
 
# File 'lib/redis.rb', line 1597

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



1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
 
# File 'lib/redis.rb', line 1922

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