Class: Redis

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

Defined Under Namespace

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

Constant Summary collapse

VERSION =
"3.3.0"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Redis

Create a new client instance

Parameters:

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

Options Hash (options):

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

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

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

    server hostname

  • :port (Fixnum) — default: 6379

    server port

  • :path (String)

    path to server socket (overrides host and port)

  • :timeout (Float) — default: 5.0

    timeout in seconds

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

    timeout for initial connect in seconds

  • :password (String)

    Password to authenticate against server

  • :db (Fixnum) — default: 0

    Database to select after initial connect

  • :driver (Symbol)

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

  • :id (String)

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

  • :tcp_keepalive (Hash, Fixnum)

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

  • :reconnect_attempts (Fixnum)

    Number of attempts trying to connect

  • :inherit_socket (Boolean) — default: false

    Whether to use socket in forked process or not

  • :sentinels (Array)

    List of sentinels to contact

  • :role (Symbol) — default: :master

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



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

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

  super() # Monitor#initialize
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(command, *args) ⇒ Object



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

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

Instance Attribute Details

#clientObject (readonly)

Returns the value of attribute client.



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

def client
  @client
end

Class Method Details

.connect(options = {}) ⇒ Object

Deprecated.

The preferred way to create a new client object is using #new. This method does not actually establish a connection to Redis, in contrary to what you might expect.



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

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

.currentObject



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

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

.current=(redis) ⇒ Object



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

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

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



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

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

Instance Method Details

#_bpop(cmd, args) ⇒ Object



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

def _bpop(cmd, args)
  options = {}

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

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

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

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

#_eval(cmd, args) ⇒ Object



2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
# File 'lib/redis.rb', line 2385

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



2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
# File 'lib/redis.rb', line 2448

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

  args << cursor

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

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

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

#append(key, value) ⇒ Fixnum

Append a value to a key.

Parameters:

  • key (String)
  • value (String)

    value to append

Returns:

  • (Fixnum)

    length of the string after appending



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

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

#auth(password) ⇒ String

Authenticate to the server.

Parameters:

  • password (String)

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

Returns:

  • (String)

    OK



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

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

#bgrewriteaofString

Asynchronously rewrite the append-only file.

Returns:

  • (String)

    OK



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

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

#bgsaveString

Asynchronously save the dataset to disk.

Returns:

  • (String)

    OK



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

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

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

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

Parameters:

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

    start index

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

    stop index

Returns:

  • (Fixnum)

    the number of bits set to 1



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

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

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

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

Parameters:

  • operation (String)

    e.g. and, or, xor, not

  • destkey (String)

    destination key

  • keys (String, Array<String>)

    one or more source keys to perform operation

Returns:

  • (Fixnum)

    the length of the string stored in destkey



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

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

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

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

Parameters:

  • key (String)
  • bit (Fixnum)

    whether to look for the first 1 or 0 bit

  • start (Fixnum) (defaults to: nil)

    start index

  • stop (Fixnum) (defaults to: nil)

    stop index

Returns:

  • (Fixnum)

    the position of the first 1/0 bit. -1 if looking for 1 and it is not found or start and stop are given.



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

def bitpos(key, bit, start=nil, stop=nil)
  if stop and not start
    raise(ArgumentError, 'stop parameter specified without start parameter')
  end

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

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

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

Examples:

With timeout

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

Without timeout

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

Blocking pop on multiple lists

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

Parameters:

  • keys (String, Array<String>)

    one or more keys to perform the blocking pop on

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

Returns:

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


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

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

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

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

Parameters:

  • keys (String, Array<String>)

    one or more keys to perform the blocking pop on

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

Returns:

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

See Also:



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

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

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

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

Parameters:

  • source (String)

    source key

  • destination (String)

    destination key

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

Returns:

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


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

def brpoplpush(source, destination, options = {})
  case options
  when Integer
    # Issue deprecation notice in obnoxious mode...
    options = { :timeout => options }
  end

  timeout = options[:timeout] || 0

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

#call(*command) ⇒ Object

Sends a command to Redis and returns its reply.

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

Redis error replies are raised as Ruby exceptions.



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

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

#closeObject Also known as: disconnect!

Disconnect the client as quickly and silently as possible.



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

def close
  @original_client.disconnect
end

#commitObject

Sends all commands in the queue.

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



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

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

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

Get or set server configuration parameters.

Parameters:

  • action (Symbol)

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

Returns:

  • (String, Hash)

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



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

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

#connected?Boolean

Test whether or not the client is connected

Returns:

  • (Boolean)


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

def connected?
  @original_client.connected?
end

#dbsizeFixnum

Return the number of keys in the selected database.

Returns:

  • (Fixnum)


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

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

#debug(*args) ⇒ Object



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

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

#decr(key) ⇒ Fixnum

Decrement the integer value of a key by one.

Examples:

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

Parameters:

  • key (String)

Returns:

  • (Fixnum)

    value after decrementing it



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

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

#decrby(key, decrement) ⇒ Fixnum

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

Examples:

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

Parameters:

  • key (String)
  • decrement (Fixnum)

Returns:

  • (Fixnum)

    value after decrementing it



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

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

#del(*keys) ⇒ Fixnum

Delete one or more keys.

Parameters:

  • keys (String, Array<String>)

Returns:

  • (Fixnum)

    number of keys that were deleted



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

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

#discardString

Discard all commands issued after MULTI.

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

Returns:

  • (String)

    "OK"

See Also:



2331
2332
2333
2334
2335
# File 'lib/redis.rb', line 2331

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

#dump(key) ⇒ String

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

Parameters:

  • key (String)

Returns:

  • (String)

    serialized_value



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

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

#dupObject



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

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

#echo(value) ⇒ String

Echo the given string.

Parameters:

  • value (String)

Returns:

  • (String)


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

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

#eval(*args) ⇒ Object

Evaluate Lua script.

Examples:

EVAL without KEYS nor ARGV

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

EVAL with KEYS and ARGV as array arguments

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

EVAL with KEYS and ARGV in a hash argument

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

Parameters:

  • keys (Array<String>)

    optional array with keys to pass to the script

  • argv (Array<String>)

    optional array with arguments to pass to the script

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

Returns:

  • depends on the script

See Also:



2419
2420
2421
# File 'lib/redis.rb', line 2419

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:



2444
2445
2446
# File 'lib/redis.rb', line 2444

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

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



2317
2318
2319
2320
2321
# File 'lib/redis.rb', line 2317

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

#exists(key) ⇒ Boolean

Determine if a key exists.

Parameters:

  • key (String)

Returns:

  • (Boolean)


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

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

#expire(key, seconds) ⇒ Boolean

Set a key's time to live in seconds.

Parameters:

  • key (String)
  • seconds (Fixnum)

    time to live

Returns:

  • (Boolean)

    whether the timeout was set or not



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

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

#expireat(key, unix_time) ⇒ Boolean

Set the expiration for a key as a UNIX timestamp.

Parameters:

  • key (String)
  • unix_time (Fixnum)

    expiry time specified as a UNIX timestamp

Returns:

  • (Boolean)

    whether the timeout was set or not



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

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

#flushallString

Remove all keys from all databases.

Returns:

  • (String)

    OK



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

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

#flushdbString

Remove all keys from the current database.

Returns:

  • (String)

    OK



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

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

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

Get the value of a key.

Parameters:

  • key (String)

Returns:

  • (String)


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

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

#getbit(key, offset) ⇒ Fixnum

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

Parameters:

  • key (String)
  • offset (Fixnum)

    bit offset

Returns:

  • (Fixnum)

    0 or 1



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

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

#getrange(key, start, stop) ⇒ Fixnum

Get a substring of the string stored at a key.

Parameters:

  • key (String)
  • start (Fixnum)

    zero-based start offset

  • stop (Fixnum)

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

Returns:

  • (Fixnum)

    0 or 1



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

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

#getset(key, value) ⇒ String

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

Parameters:

  • key (String)
  • value (String)

    value to replace the current value with

Returns:

  • (String)

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



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

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

#hdel(key, field) ⇒ Fixnum

Delete one or more hash fields.

Parameters:

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

Returns:

  • (Fixnum)

    the number of fields that were removed from the hash



2051
2052
2053
2054
2055
# File 'lib/redis.rb', line 2051

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



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

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)


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

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


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

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



2074
2075
2076
2077
2078
# File 'lib/redis.rb', line 2074

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



2086
2087
2088
2089
2090
# File 'lib/redis.rb', line 2086

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


2096
2097
2098
2099
2100
# File 'lib/redis.rb', line 2096

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



1935
1936
1937
1938
1939
# File 'lib/redis.rb', line 1935

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:



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

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:



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

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



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

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



2538
2539
2540
2541
2542
2543
2544
2545
2546
# File 'lib/redis.rb', line 2538

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



1947
1948
1949
1950
1951
# File 'lib/redis.rb', line 1947

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



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

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


2106
2107
2108
2109
2110
# File 'lib/redis.rb', line 2106

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

#idObject



2686
2687
2688
# File 'lib/redis.rb', line 2686

def id
  @original_client.id
end

#incr(key) ⇒ Fixnum

Increment the integer value of a key by one.

Examples:

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

Parameters:

  • key (String)

Returns:

  • (Fixnum)

    value after incrementing it



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

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

#incrby(key, increment) ⇒ Fixnum

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

Examples:

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

Parameters:

  • key (String)
  • increment (Fixnum)

Returns:

  • (Fixnum)

    value after incrementing it



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

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

#incrbyfloat(key, increment) ⇒ Float

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

Examples:

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

Parameters:

  • key (String)
  • increment (Float)

Returns:

  • (Float)

    value after incrementing it



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

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

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

Get information and statistics about the server.

Parameters:

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

    e.g. "commandstats"

Returns:

  • (Hash<String, String>)


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

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

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

      reply
    end
  end
end

#inspectObject



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

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

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

Find all keys matching the given pattern.

Parameters:

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

Returns:

  • (Array<String>)


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

def keys(pattern = "*")
  synchronize do |client|
    client.call([:keys, pattern]) do |reply|
      if reply.kind_of?(String)
        reply.split(" ")
      else
        reply
      end
    end
  end
end

#lastsaveFixnum

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

Returns:

  • (Fixnum)


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

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

#lindex(key, index) ⇒ String

Get an element from a list by its index.

Parameters:

  • key (String)
  • index (Fixnum)

Returns:

  • (String)


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

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

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

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

Parameters:

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

    BEFORE or AFTER

  • pivot (String)

    reference element

  • value (String)

Returns:

  • (Fixnum)

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



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

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

#llen(key) ⇒ Fixnum

Get the length of a list.

Parameters:

  • key (String)

Returns:

  • (Fixnum)


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

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

#lpop(key) ⇒ String

Remove and get the first element in a list.

Parameters:

  • key (String)

Returns:

  • (String)


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

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

#lpush(key, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • value (String, Array)

    string value, or array of string values to push

Returns:

  • (Fixnum)

    the length of the list after the push operation



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

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

#lpushx(key, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • value (String)

Returns:

  • (Fixnum)

    the length of the list after the push operation



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

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

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

Get a range of elements from a list.

Parameters:

  • key (String)
  • start (Fixnum)

    start index

  • stop (Fixnum)

    stop index

Returns:

  • (Array<String>)


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

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

#lrem(key, count, value) ⇒ Fixnum

Remove elements from a list.

Parameters:

  • key (String)
  • count (Fixnum)

    number of elements to remove. Use a positive value to remove the first count occurrences of value. A negative value to remove the last count occurrences of value. Or zero, to remove all occurrences of value from the list.

  • value (String)

Returns:

  • (Fixnum)

    the number of removed elements



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

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

#lset(key, index, value) ⇒ String

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

Parameters:

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

Returns:

  • (String)

    OK



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

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

#ltrim(key, start, stop) ⇒ String

Trim a list to the specified range.

Parameters:

  • key (String)
  • start (Fixnum)

    start index

  • stop (Fixnum)

    stop index

Returns:

  • (String)

    OK



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

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

#mapped_hmget(key, *fields) ⇒ Hash

Get the values of all the given hash fields.

Examples:

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

Parameters:

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

    array of fields

Returns:

  • (Hash)

    a hash mapping the specified fields to their values

See Also:



2036
2037
2038
2039
2040
2041
2042
2043
2044
# File 'lib/redis.rb', line 2036

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:



1993
1994
1995
# File 'lib/redis.rb', line 1993

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

#mapped_mget(*keys) ⇒ Hash

Get the values of all the given keys.

Examples:

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

Parameters:

  • keys (Array<String>)

    array of keys

Returns:

  • (Hash)

    a hash mapping the specified keys to their values

See Also:



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

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

#mapped_mset(hash) ⇒ String

Set one or more values.

Examples:

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

Parameters:

  • hash (Hash)

    keys mapping to values

Returns:

  • (String)

    "OK"

See Also:



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

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

#mapped_msetnx(hash) ⇒ Boolean

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

Examples:

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

Parameters:

  • hash (Hash)

    keys mapping to values

Returns:

  • (Boolean)

    whether or not all values were set

See Also:



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

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

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

Get the values of all the given keys.

Examples:

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

Parameters:

  • keys (Array<String>)

Returns:

  • (Array<String>)

    an array of values for the specified keys

See Also:



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

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

#migrate(key, options) ⇒ String

Transfer a key from the connected instance to another instance.

Parameters:

  • key (String)
  • options (Hash)
    • :host => String: host of instance to migrate to
    • :port => Integer: port of instance to migrate to
    • :db => Integer: database to migrate to (default: same as source)
    • :timeout => Integer: timeout (default: same as connection timeout)

Returns:

  • (String)

    "OK"



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

def migrate(key, options)
  host = options[:host] || raise(RuntimeError, ":host not specified")
  port = options[:port] || raise(RuntimeError, ":port not specified")
  db = (options[:db] || client.db).to_i
  timeout = (options[:timeout] || client.timeout).to_i

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

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

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

There is no way to interrupt this command.

Yields:

  • a block to be called for every line of output

Yield Parameters:

  • line (String)

    timestamp and command that was executed



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

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

#move(key, db) ⇒ Boolean

Move a key to another database.

Examples:

Move a key to another database

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

Parameters:

  • key (String)
  • db (Fixnum)

Returns:

  • (Boolean)

    whether the key was moved or not



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

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

#mset(*args) ⇒ String

Set one or more values.

Examples:

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

Parameters:

  • args (Array<String>)

    array of keys and values

Returns:

  • (String)

    "OK"

See Also:



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

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

#msetnx(*args) ⇒ Boolean

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

Examples:

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

Parameters:

  • args (Array<String>)

    array of keys and values

Returns:

  • (Boolean)

    whether or not all values were set

See Also:



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

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

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

Mark the start of a transaction block.

Passing a block is optional.

Examples:

With a block

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

Without a block

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

Yields:

  • (multi)

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

Yield Parameters:

Returns:

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

See Also:



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

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

#object(*args) ⇒ Object



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

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

#persist(key) ⇒ Boolean

Remove the expiration from a key.

Parameters:

  • key (String)

Returns:

  • (Boolean)

    whether the timeout was removed or not



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

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

#pexpire(key, milliseconds) ⇒ Boolean

Set a key's time to live in milliseconds.

Parameters:

  • key (String)
  • milliseconds (Fixnum)

    time to live

Returns:

  • (Boolean)

    whether the timeout was set or not



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

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

#pexpireat(key, ms_unix_time) ⇒ Boolean

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

Parameters:

  • key (String)
  • ms_unix_time (Fixnum)

    expiry time specified as number of milliseconds from UNIX Epoch.

Returns:

  • (Boolean)

    whether the timeout was set or not



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

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

#pfadd(key, member) ⇒ Boolean

Add one or more members to a HyperLogLog structure.

Parameters:

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

    one member, or array of members

Returns:

  • (Boolean)

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



2628
2629
2630
2631
2632
# File 'lib/redis.rb', line 2628

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)


2641
2642
2643
2644
2645
# File 'lib/redis.rb', line 2641

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)


2653
2654
2655
2656
2657
# File 'lib/redis.rb', line 2653

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

#pingString

Ping the server.

Returns:

  • (String)

    PONG



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

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

#pipelinedObject



2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
# File 'lib/redis.rb', line 2248

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

#psetex(key, ttl, value) ⇒ String

Set the time to live in milliseconds of a key.

Parameters:

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

Returns:

  • (String)

    "OK"



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

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

#psubscribe(*channels, &block) ⇒ Object

Listen for messages published to channels matching the given patterns.



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

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.



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

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

#pttl(key) ⇒ Fixnum

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

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

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

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

Parameters:

  • key (String)

Returns:

  • (Fixnum)

    remaining time to live in milliseconds



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

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

#publish(channel, message) ⇒ Object

Post a message to a channel.



2123
2124
2125
2126
2127
# File 'lib/redis.rb', line 2123

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.



2181
2182
2183
2184
2185
# File 'lib/redis.rb', line 2181

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.



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

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

#queue(*command) ⇒ Object

Queues a command for pipelining.

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

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



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

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

#quitString

Close the connection.

Returns:

  • (String)

    OK



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

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

#randomkeyString

Return a random key from the keyspace.

Returns:

  • (String)


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

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

#rename(old_name, new_name) ⇒ String

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

Parameters:

  • old_name (String)
  • new_name (String)

Returns:

  • (String)

    OK



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

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

#renamenx(old_name, new_name) ⇒ Boolean

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

Parameters:

  • old_name (String)
  • new_name (String)

Returns:

  • (Boolean)

    whether the key was renamed or not



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

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

#restore(key, ttl, serialized_value) ⇒ String

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

Parameters:

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

Returns:

  • (String)

    "OK"



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

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

#rpop(key) ⇒ String

Remove and get the last element in a list.

Parameters:

  • key (String)

Returns:

  • (String)


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

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

#rpoplpush(source, destination) ⇒ nil, String

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

Parameters:

  • source (String)

    source key

  • destination (String)

    destination key

Returns:

  • (nil, String)

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



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

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

#rpush(key, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • value (String)

Returns:

  • (Fixnum)

    the length of the list after the push operation



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

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

#rpushx(key, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • value (String)

Returns:

  • (Fixnum)

    the length of the list after the push operation



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

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

#sadd(key, member) ⇒ Boolean, Fixnum

Add one or more members to a set.

Parameters:

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

    one member, or array of members

Returns:

  • (Boolean, Fixnum)

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



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

def sadd(key, member)
  synchronize do |client|
    client.call([:sadd, key, member]) do |reply|
      if member.is_a? Array
        # Variadic: return integer
        reply
      else
        # Single argument: return boolean
        Boolify.call(reply)
      end
    end
  end
end

#saveString

Synchronously save the dataset to disk.

Returns:

  • (String)


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

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

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

Scan the keyspace

Examples:

Retrieve the first batch of keys

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

Retrieve a batch of keys matching a pattern

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

Parameters:

  • cursor (String, Integer)

    the cursor of the iteration

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

Returns:

  • (String, Array<String>)

    the next cursor and all found keys



2481
2482
2483
# File 'lib/redis.rb', line 2481

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



2500
2501
2502
2503
2504
2505
2506
2507
2508
# File 'lib/redis.rb', line 2500

def scan_each(options={}, &block)
  return to_enum(:scan_each, options) unless block_given?
  cursor = 0
  loop do
    cursor, keys = scan(cursor, options)
    keys.each(&block)
    break if cursor == "0"
  end
end

#scard(key) ⇒ Fixnum

Get the number of members in a set.

Parameters:

  • key (String)

Returns:

  • (Fixnum)


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

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

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

Control remote script registry.

Examples:

Load a script

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

Check if a script exists

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

Check if multiple scripts exist

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

Flush the script registry

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

Kill a running script

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

Parameters:

  • subcommand (String)

    e.g. exists, flush, load, kill

  • args (Array<String>)

    depends on subcommand

Returns:

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

    depends on subcommand

See Also:



2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
# File 'lib/redis.rb', line 2361

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



1401
1402
1403
1404
1405
# File 'lib/redis.rb', line 1401

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



1412
1413
1414
1415
1416
# File 'lib/redis.rb', line 1412

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

#select(db) ⇒ String

Change the selected database for the current connection.

Parameters:

  • db (Fixnum)

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

Returns:

  • (String)

    OK



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

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

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

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

Parameters:

  • subcommand (String)

    e.g. masters, master, slaves

  • args (Array<String>)

    depends on subcommand

Returns:

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

    depends on subcommand



2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
# File 'lib/redis.rb', line 2664

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

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

Set the string value of a key.

Parameters:

  • key (String)
  • value (String)
  • options (Hash) (defaults to: {})
    • :ex => Fixnum: Set the specified expire time, in seconds.
    • :px => Fixnum: Set the specified expire time, in milliseconds.
    • :nx => true: Only set the key if it does not already exist.
    • :xx => true: Only set the key if it already exist.

Returns:

  • (String, Boolean)

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



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

def set(key, value, options = {})
  args = []

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

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

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

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

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

#setbit(key, offset, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • offset (Fixnum)

    bit offset

  • value (Fixnum)

    bit value 0 or 1

Returns:

  • (Fixnum)

    the original bit value stored at offset



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

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

#setex(key, ttl, value) ⇒ String

Set the time to live in seconds of a key.

Parameters:

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

Returns:

  • (String)

    "OK"



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

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

#setnx(key, value) ⇒ Boolean

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

Parameters:

  • key (String)
  • value (String)

Returns:

  • (Boolean)

    whether the key was set or not



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

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

#setrange(key, offset, value) ⇒ Fixnum

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

Parameters:

  • key (String)
  • offset (Fixnum)

    byte offset

  • value (String)

Returns:

  • (Fixnum)

    length of the string after it was modified



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

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

#shutdownObject

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



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

def shutdown
  synchronize do |client|
    client.with_reconnect(false) do
      begin
        client.call([:shutdown])
      rescue ConnectionError
        # This means Redis has probably exited.
        nil
      end
    end
  end
end

#sinter(*keys) ⇒ Array<String>

Intersect multiple sets.

Parameters:

  • keys (String, Array<String>)

    keys pointing to sets to intersect

Returns:

  • (Array<String>)

    members in the intersection



1422
1423
1424
1425
1426
# File 'lib/redis.rb', line 1422

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



1433
1434
1435
1436
1437
# File 'lib/redis.rb', line 1433

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)


1381
1382
1383
1384
1385
# File 'lib/redis.rb', line 1381

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

#slaveof(host, port) ⇒ Object

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



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

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

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

Interact with the slowlog (get, len, reset)

Parameters:

  • subcommand (String)

    e.g. get, len, reset

  • length (Fixnum) (defaults to: nil)

    maximum number of entries to return

Returns:

  • (Array<String>, Fixnum, String)

    depends on subcommand



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

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

#smembers(key) ⇒ Array<String>

Get all the members in a set.

Parameters:

  • key (String)

Returns:

  • (Array<String>)


1391
1392
1393
1394
1395
# File 'lib/redis.rb', line 1391

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)


1370
1371
1372
1373
1374
# File 'lib/redis.rb', line 1370

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

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

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

Examples:

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

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

Store an alphabetically descending list in "target"

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

Parameters:

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

Returns:

  • (Array<String>, Array<Array<String>>, Fixnum)
    • when :get is not specified, or holds a single element, an array of elements
    • when :get is specified, and holds more than one element, an array of elements where every element is an array with the result for every element specified in :get
    • when :store is specified, the number of elements in the stored result


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

def sort(key, options = {})
  args = []

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

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

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

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

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

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

#spop(key) ⇒ String

Remove and return a random member from a set.

Parameters:

  • key (String)

Returns:

  • (String)


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

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

#srandmember(key, count = nil) ⇒ String

Get one or more random members from a set.

Parameters:

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

Returns:

  • (String)


1354
1355
1356
1357
1358
1359
1360
1361
1362
# File 'lib/redis.rb', line 1354

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

#srem(key, member) ⇒ Boolean, Fixnum

Remove one or more members from a set.

Parameters:

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

    one member, or array of members

Returns:

  • (Boolean, Fixnum)

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



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

def srem(key, member)
  synchronize do |client|
    client.call([:srem, key, member]) do |reply|
      if member.is_a? Array
        # Variadic: return integer
        reply
      else
        # Single argument: return boolean
        Boolify.call(reply)
      end
    end
  end
end

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

Scan a set

Examples:

Retrieve the first batch of keys in a set

redis.sscan("set", 0)

Parameters:

  • cursor (String, Integer)

    the cursor of the iteration

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

Returns:

  • (String, Array<String>)

    the next cursor and all found members



2598
2599
2600
# File 'lib/redis.rb', line 2598

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



2613
2614
2615
2616
2617
2618
2619
2620
2621
# File 'lib/redis.rb', line 2613

def sscan_each(key, options={}, &block)
  return to_enum(:sscan_each, key, options) unless block_given?
  cursor = 0
  loop do
    cursor, keys = sscan(key, cursor, options)
    keys.each(&block)
    break if cursor == "0"
  end
end

#strlen(key) ⇒ Fixnum

Get the length of the value stored in a key.

Parameters:

  • key (String)

Returns:

  • (Fixnum)

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



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

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

#subscribe(*channels, &block) ⇒ Object

Listen for messages published to the given channels.



2136
2137
2138
2139
2140
# File 'lib/redis.rb', line 2136

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.



2143
2144
2145
2146
2147
# File 'lib/redis.rb', line 2143

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

#subscribed?Boolean

Returns:

  • (Boolean)


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

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



1443
1444
1445
1446
1447
# File 'lib/redis.rb', line 1443

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



1454
1455
1456
1457
1458
# File 'lib/redis.rb', line 1454

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

#syncObject

Internal command used for replication.



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

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

#synchronizeObject



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

def synchronize
  mon_synchronize { yield(@client) }
end

#timeArray<Fixnum>

Return the server time.

Examples:

r.time # => [ 1333093196, 606806 ]

Returns:

  • (Array<Fixnum>)

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



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

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

#ttl(key) ⇒ Fixnum

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

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

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

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

Parameters:

  • key (String)

Returns:

  • (Fixnum)

    remaining time to live in seconds.



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

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

#type(key) ⇒ String

Determine the type stored at key.

Parameters:

  • key (String)

Returns:

  • (String)

    string, list, set, zset, hash or none



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

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

#unsubscribe(*channels) ⇒ Object

Stop listening for messages posted to the given channels.



2150
2151
2152
2153
2154
2155
# File 'lib/redis.rb', line 2150

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

#unwatchString

Forget about all watched keys.

Returns:

  • (String)

    OK

See Also:



2242
2243
2244
2245
2246
# File 'lib/redis.rb', line 2242

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:



2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
# File 'lib/redis.rb', line 2217

def watch(*keys)
  synchronize do |client|
    res = client.call([:watch] + keys)

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

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

Run code with the client reconnecting



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

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

#without_reconnect(&blk) ⇒ Object

Run code without the client reconnecting



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

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

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

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

Examples:

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

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

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

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

Parameters:

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

Returns:

  • (Boolean, Fixnum, Float)
    • Boolean when a single pair is specified, holding whether or not it was added to the sorted set.
    • Fixnum when an array of pairs is specified, holding the number of pairs that were added to the sorted set.
    • Float when option :incr is specified, holding the score of the member after incrementing it.


1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
# File 'lib/redis.rb', line 1505

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)


1468
1469
1470
1471
1472
# File 'lib/redis.rb', line 1468

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



1870
1871
1872
1873
1874
# File 'lib/redis.rb', line 1870

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



1546
1547
1548
1549
1550
# File 'lib/redis.rb', line 1546

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



1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
# File 'lib/redis.rb', line 1890

def zinterstore(destination, keys, options = {})
  args = []

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

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

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

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

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

Examples:

Retrieve all members from a sorted set

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

Retrieve all members and their scores from a sorted set

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

Parameters:

  • key (String)
  • start (Fixnum)

    start index

  • stop (Fixnum)

    stop index

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

Returns:

  • (Array<String>, Array<[String, Float]>)
    • when :with_scores is not specified, an array of members
    • when :with_scores is specified, an array with [member, score] pairs


1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
# File 'lib/redis.rb', line 1616

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


1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
# File 'lib/redis.rb', line 1720

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


1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
# File 'lib/redis.rb', line 1780

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)


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

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


1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
# File 'lib/redis.rb', line 1569

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



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

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



1847
1848
1849
1850
1851
# File 'lib/redis.rb', line 1847

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:



1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
# File 'lib/redis.rb', line 1642

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:



1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
# File 'lib/redis.rb', line 1742

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:



1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
# File 'lib/redis.rb', line 1812

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)


1674
1675
1676
1677
1678
# File 'lib/redis.rb', line 1674

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



2560
2561
2562
2563
2564
# File 'lib/redis.rb', line 2560

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



2577
2578
2579
2580
2581
2582
2583
2584
2585
# File 'lib/redis.rb', line 2577

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



1592
1593
1594
1595
1596
# File 'lib/redis.rb', line 1592

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



1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
# File 'lib/redis.rb', line 1917

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