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, CannotConnectError, Client, CommandError, ConnectionError, Distributed, Future, FutureNotReady, HashRing, InheritedError, Pipeline, ProtocolError, SubscribedClient, Subscription, TimeoutError

Constant Summary collapse

VERSION = 
"4.0.0"

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



36
37
38
39
40
41
42
 
# File 'lib/redis.rb', line 36

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 



2740
2741
2742
2743
2744
 
# File 'lib/redis.rb', line 2740

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

Class Method Details

.current ⇒ Object 



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

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

.current=(redis) ⇒ Object 



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

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

Instance Method Details

#_bpop(cmd, args) ⇒ Object 



1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
 
# File 'lib/redis.rb', line 1129

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

#_client ⇒ Object 



109
110
111
 
# File 'lib/redis.rb', line 109

def _client
  @client
end

#_eval(cmd, args) ⇒ Object 



2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
 
# File 'lib/redis.rb', line 2427

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 



2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
 
# File 'lib/redis.rb', line 2490

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



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

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



118
119
120
121
122
 
# File 'lib/redis.rb', line 118

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

#bgrewriteaof ⇒ String

Asynchronously rewrite the append-only file.

Returns:

  • (String) —

    OK



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

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

#bgsave ⇒ String

Asynchronously save the dataset to disk.

Returns:

  • (String) —

    OK



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

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



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

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



994
995
996
997
998
 
# File 'lib/redis.rb', line 994

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.



1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
 
# File 'lib/redis.rb', line 1008

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


1175
1176
1177
 
# File 'lib/redis.rb', line 1175

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:



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

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


1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
 
# File 'lib/redis.rb', line 1206

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.



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

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

#client(subcommand = nil, *args) ⇒ String, Hash

Manage client connections.

Parameters:

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

    e.g. kill, list, getname, setname

Returns:

  • (String, Hash) —

    depends on subcommand



208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/redis.rb', line 208

def client(subcommand = nil, *args)
  synchronize do |client|
    client.call([:client, subcommand] + args) do |reply|
      if subcommand.to_s == "list"
        reply.lines.map do |line|
          entries = line.chomp.split(/[ =]/)
          Hash[entries.each_slice(2).to_a]
        end
      else
        reply
      end
    end
  end
end

#close ⇒ Object Also known as: disconnect!

Disconnect the client as quickly and silently as possible.



66
67
68
 
# File 'lib/redis.rb', line 66

def close
  @original_client.disconnect
end

#commit ⇒ Object

Sends all commands in the queue.

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



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

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



192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/redis.rb', line 192

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) 


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

def connected?
  @original_client.connected?
end

#dbsize ⇒ Fixnum

Return the number of keys in the selected database.

Returns:

  • (Fixnum) 


226
227
228
229
230
 
# File 'lib/redis.rb', line 226

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

#debug(*args) ⇒ Object 



232
233
234
235
236
 
# File 'lib/redis.rb', line 232

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



677
678
679
680
681
 
# File 'lib/redis.rb', line 677

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



692
693
694
695
696
 
# File 'lib/redis.rb', line 692

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



509
510
511
512
513
 
# File 'lib/redis.rb', line 509

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:



2373
2374
2375
2376
2377
 
# File 'lib/redis.rb', line 2373

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



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

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

#dup ⇒ Object 



2736
2737
2738
 
# File 'lib/redis.rb', line 2736

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

#echo(value) ⇒ String

Echo the given string.

Parameters:

  • value (String)

Returns:

  • (String) 


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

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:



2461
2462
2463
 
# File 'lib/redis.rb', line 2461

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:



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

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:



2359
2360
2361
2362
2363
 
# File 'lib/redis.rb', line 2359

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

#exists(key) ⇒ Boolean

Determine if a key exists.

Parameters:

  • key (String)

Returns:

  • (Boolean) 


519
520
521
522
523
 
# File 'lib/redis.rb', line 519

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



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

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



394
395
396
397
398
 
# File 'lib/redis.rb', line 394

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



241
242
243
244
245
 
# File 'lib/redis.rb', line 241

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

#flushdb ⇒ String

Remove all keys from the current database.

Returns:

  • (String) —

    OK



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

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

#get(key) ⇒ String

Get the value of a key.

Parameters:

  • key (String)

Returns:

  • (String) 


875
876
877
878
879
 
# File 'lib/redis.rb', line 875

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



959
960
961
962
963
 
# File 'lib/redis.rb', line 959

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



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

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



1027
1028
1029
1030
1031
 
# File 'lib/redis.rb', line 1027

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



2093
2094
2095
2096
2097
 
# File 'lib/redis.rb', line 2093

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



2104
2105
2106
2107
2108
 
# File 'lib/redis.rb', line 2104

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) 


2044
2045
2046
2047
2048
 
# File 'lib/redis.rb', line 2044

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


2158
2159
2160
2161
2162
 
# File 'lib/redis.rb', line 2158

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



2116
2117
2118
2119
2120
 
# File 'lib/redis.rb', line 2116

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



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

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


2138
2139
2140
2141
2142
 
# File 'lib/redis.rb', line 2138

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



1977
1978
1979
1980
1981
 
# File 'lib/redis.rb', line 1977

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:



2061
2062
2063
2064
2065
 
# File 'lib/redis.rb', line 2061

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:



2018
2019
2020
2021
2022
 
# File 'lib/redis.rb', line 2018

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



2563
2564
2565
2566
2567
 
# File 'lib/redis.rb', line 2563

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



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

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



1989
1990
1991
1992
1993
 
# File 'lib/redis.rb', line 1989

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



2001
2002
2003
2004
2005
 
# File 'lib/redis.rb', line 2001

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


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

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

#id ⇒ Object 



2728
2729
2730
 
# File 'lib/redis.rb', line 2728

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



706
707
708
709
710
 
# File 'lib/redis.rb', line 706

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



721
722
723
724
725
 
# File 'lib/redis.rb', line 721

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



736
737
738
739
740
 
# File 'lib/redis.rb', line 736

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


260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
 
# File 'lib/redis.rb', line 260

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 



2732
2733
2734
 
# File 'lib/redis.rb', line 2732

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


529
530
531
532
533
534
535
536
537
538
539
 
# File 'lib/redis.rb', line 529

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) 


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

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) 


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

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



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

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) 


1048
1049
1050
1051
1052
 
# File 'lib/redis.rb', line 1048

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) 


1102
1103
1104
1105
1106
 
# File 'lib/redis.rb', line 1102

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

    string value, or array of string values to push

Returns:

  • (Fixnum) —

    the length of the list after the push operation



1059
1060
1061
1062
1063
 
# File 'lib/redis.rb', line 1059

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



1070
1071
1072
1073
1074
 
# File 'lib/redis.rb', line 1070

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


1253
1254
1255
1256
1257
 
# File 'lib/redis.rb', line 1253

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



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

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



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

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



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

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:



2078
2079
2080
2081
2082
2083
2084
2085
2086
 
# File 'lib/redis.rb', line 2078

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:



2035
2036
2037
 
# File 'lib/redis.rb', line 2035

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:



907
908
909
910
911
912
913
914
915
 
# File 'lib/redis.rb', line 907

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:



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

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:



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

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:



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

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"



494
495
496
497
498
499
500
501
502
503
 
# File 'lib/redis.rb', line 494

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



297
298
299
300
301
 
# File 'lib/redis.rb', line 297

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



560
561
562
563
564
 
# File 'lib/redis.rb', line 560

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:



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

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:



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

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:



2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
 
# File 'lib/redis.rb', line 2332

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 



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

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



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

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



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

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



434
435
436
437
438
 
# File 'lib/redis.rb', line 434

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.



2670
2671
2672
2673
2674
 
# File 'lib/redis.rb', line 2670

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) 


2683
2684
2685
2686
2687
 
# File 'lib/redis.rb', line 2683

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) 


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

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

#ping(message = nil) ⇒ String

Ping the server.

Parameters:

  • message (optional, String) (defaults to: nil)

Returns:

  • (String) —

    PONG



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

def ping(message = nil)
  synchronize do |client|
    client.call([:ping, message].compact)
  end
end

#pipelined ⇒ Object 



2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
 
# File 'lib/redis.rb', line 2290

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"



794
795
796
797
798
 
# File 'lib/redis.rb', line 794

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.



2200
2201
2202
2203
2204
 
# File 'lib/redis.rb', line 2200

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.



2207
2208
2209
2210
2211
 
# File 'lib/redis.rb', line 2207

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



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

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

#publish(channel, message) ⇒ Object

Post a message to a channel.



2165
2166
2167
2168
2169
 
# File 'lib/redis.rb', line 2165

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.



2223
2224
2225
2226
2227
 
# File 'lib/redis.rb', line 2223

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.



2214
2215
2216
2217
2218
2219
 
# File 'lib/redis.rb', line 2214

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.



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

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

#quit ⇒ String

Close the connection.

Returns:

  • (String) —

    OK



158
159
160
161
162
163
164
165
166
167
 
# File 'lib/redis.rb', line 158

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) 


575
576
577
578
579
 
# File 'lib/redis.rb', line 575

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



586
587
588
589
590
 
# File 'lib/redis.rb', line 586

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



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

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

#restore(key, ttl, serialized_value, options = {}) ⇒ String

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

Parameters:

  • key (String)
  • ttl (String)
  • serialized_value (String)
  • options (Hash) (defaults to: {}) —
    • :replace => Boolean: if false, raises an error if key already exists

Returns:

  • (String) —

    "OK"

Raises:



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

def restore(key, ttl, serialized_value, options = {})
  args = [:restore, key, ttl, serialized_value]
  args << 'REPLACE' if options[:replace]

  synchronize do |client|
    client.call(args)
  end
end

#rpop(key) ⇒ String

Remove and get the last element in a list.

Parameters:

  • key (String)

Returns:

  • (String) 


1112
1113
1114
1115
1116
 
# File 'lib/redis.rb', line 1112

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



1123
1124
1125
1126
1127
 
# File 'lib/redis.rb', line 1123

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

    string value, or array of string values to push

Returns:

  • (Fixnum) —

    the length of the list after the push operation



1081
1082
1083
1084
1085
 
# File 'lib/redis.rb', line 1081

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



1092
1093
1094
1095
1096
 
# File 'lib/redis.rb', line 1092

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



1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
 
# File 'lib/redis.rb', line 1316

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) 


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

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



2523
2524
2525
 
# File 'lib/redis.rb', line 2523

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



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

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) 


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

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:



2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
 
# File 'lib/redis.rb', line 2403

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



1419
1420
1421
1422
1423
 
# File 'lib/redis.rb', line 1419

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



1430
1431
1432
1433
1434
 
# File 'lib/redis.rb', line 1430

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



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

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



2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
 
# File 'lib/redis.rb', line 2706

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

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



752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
 
# File 'lib/redis.rb', line 752

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



948
949
950
951
952
 
# File 'lib/redis.rb', line 948

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"



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

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



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

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



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

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.



313
314
315
316
317
318
319
320
321
322
323
324
 
# File 'lib/redis.rb', line 313

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



1440
1441
1442
1443
1444
 
# File 'lib/redis.rb', line 1440

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



1451
1452
1453
1454
1455
 
# File 'lib/redis.rb', line 1451

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) 


1399
1400
1401
1402
1403
 
# File 'lib/redis.rb', line 1399

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.



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

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



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

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


1409
1410
1411
1412
1413
 
# File 'lib/redis.rb', line 1409

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) 


1388
1389
1390
1391
1392
 
# File 'lib/redis.rb', line 1388

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


628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
 
# File 'lib/redis.rb', line 628

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) 


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

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) 


1372
1373
1374
1375
1376
1377
1378
1379
1380
 
# File 'lib/redis.rb', line 1372

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



1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
 
# File 'lib/redis.rb', line 1338

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



2640
2641
2642
 
# File 'lib/redis.rb', line 2640

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



2655
2656
2657
2658
2659
2660
2661
2662
2663
 
# File 'lib/redis.rb', line 2655

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



1038
1039
1040
1041
1042
 
# File 'lib/redis.rb', line 1038

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

#subscribe(*channels, &block) ⇒ Object

Listen for messages published to the given channels.



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

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.



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

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

#subscribed? ⇒ Boolean

Returns:

  • (Boolean) 


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

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



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

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



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

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

#sync ⇒ Object

Internal command used for replication.



347
348
349
350
351
 
# File 'lib/redis.rb', line 347

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

#synchronize ⇒ Object 



44
45
46
 
# File 'lib/redis.rb', line 44

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



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

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.



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

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



663
664
665
666
667
 
# File 'lib/redis.rb', line 663

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

#unsubscribe(*channels) ⇒ Object

Stop listening for messages posted to the given channels.



2192
2193
2194
2195
2196
2197
 
# File 'lib/redis.rb', line 2192

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:



2284
2285
2286
2287
2288
 
# File 'lib/redis.rb', line 2284

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:



2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
 
# File 'lib/redis.rb', line 2259

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



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

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



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

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.


1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
 
# File 'lib/redis.rb', line 1523

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) 


1486
1487
1488
1489
1490
 
# File 'lib/redis.rb', line 1486

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



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

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



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

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



1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
 
# File 'lib/redis.rb', line 1932

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

#zlexcount(key, min, max) ⇒ Fixnum

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

Examples:

Count members matching a

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

Count members matching a-z

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

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 [

Returns:

  • (Fixnum) —

    number of members within the specified lexicographical range



1735
1736
1737
1738
1739
 
# File 'lib/redis.rb', line 1735

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


1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
 
# File 'lib/redis.rb', line 1634

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


1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
 
# File 'lib/redis.rb', line 1762

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


1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
 
# File 'lib/redis.rb', line 1822

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) 


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

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


1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
 
# File 'lib/redis.rb', line 1587

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



1711
1712
1713
1714
1715
 
# File 'lib/redis.rb', line 1711

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



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

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:



1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
 
# File 'lib/redis.rb', line 1660

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:



1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
 
# File 'lib/redis.rb', line 1784

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:



1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
 
# File 'lib/redis.rb', line 1854

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) 


1692
1693
1694
1695
1696
 
# File 'lib/redis.rb', line 1692

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



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

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



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

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



1610
1611
1612
1613
1614
 
# File 'lib/redis.rb', line 1610

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



1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
 
# File 'lib/redis.rb', line 1959

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