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, Pipeline, ProtocolError, SubscribedClient, Subscription, TimeoutError

Constant Summary collapse

VERSION =
"3.0.0.rc1"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Redis

Returns a new instance of Redis.



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

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

  super() # Monitor#initialize
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(command, *args) ⇒ Object



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

def method_missing(command, *args)
  synchronize do
    @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



12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# File 'lib/redis.rb', line 12

def self.connect(options = {})
  options = options.dup

  url = options.delete(:url) || ENV["REDIS_URL"]
  if url
    require "uri"

    uri = URI(url)

    # Require the URL to have at least a host
    raise ArgumentError, "invalid url" unless uri.host

    options[:host]     ||= uri.host
    options[:port]     ||= uri.port
    options[:password] ||= uri.password
    options[:db]       ||= uri.path[1..-1].to_i
  end

  new(options)
end

.currentObject



33
34
35
# File 'lib/redis.rb', line 33

def self.current
  Thread.current[:redis] ||= Redis.connect
end

.current=(redis) ⇒ Object



37
38
39
# File 'lib/redis.rb', line 37

def self.current=(redis)
  Thread.current[:redis] = 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

#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



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

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

#auth(password) ⇒ String

Authenticate to the server.

Parameters:

  • password (String)

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

Returns:

  • (String)

    OK



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

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

#bgrewriteaofString

Asynchronously rewrite the append-only file.

Returns:

  • (String)

    OK



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

def bgrewriteaof
  synchronize do
    @client.call [:bgrewriteaof]
  end
end

#bgsaveString

Asynchronously save the dataset to disk.

Returns:

  • (String)

    OK



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

def bgsave
  synchronize do
    @client.call [:bgsave]
  end
end

#blpop(keys, options = {}) ⇒ 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) (defaults to: {})
    • :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


534
535
536
537
538
539
540
# File 'lib/redis.rb', line 534

def blpop(keys, options = {})
  timeout = options[:timeout] || 0

  synchronize do
    @client.call_without_timeout [:blpop, keys, timeout]
  end
end

#brpop(keys, options = {}) ⇒ 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) (defaults to: {})
    • :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:



554
555
556
557
558
559
560
# File 'lib/redis.rb', line 554

def brpop(keys, options = {})
  timeout = options[:timeout] || 0

  synchronize do
    @client.call_without_timeout [:brpop, keys, timeout]
  end
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


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

def brpoplpush(source, destination, options = {})
  timeout = options[:timeout] || 0

  synchronize do
    @client.call_without_timeout [:brpoplpush, source, destination, timeout]
  end
end

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

Get or set server configuration parameters.

Parameters:

  • action (String)

    e.g. get, set, resetstat

Returns:

  • (String, Hash)

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



106
107
108
109
110
111
112
113
114
115
116
# File 'lib/redis.rb', line 106

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

#dbsizeFixnum

Return the number of keys in the selected database.

Returns:

  • (Fixnum)


357
358
359
360
361
# File 'lib/redis.rb', line 357

def dbsize
  synchronize do
    @client.call [:dbsize]
  end
end

#debug(*args) ⇒ Object



1464
1465
1466
1467
1468
# File 'lib/redis.rb', line 1464

def debug(*args)
  synchronize do
    @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



1709
1710
1711
1712
1713
# File 'lib/redis.rb', line 1709

def decr(key)
  synchronize do
    @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



1724
1725
1726
1727
1728
# File 'lib/redis.rb', line 1724

def decrby(key, decrement)
  synchronize do
    @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



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

def del(*keys)
  synchronize do
    @client.call [:del, *keys]
  end
end

#discardObject

Discard all commands issued after MULTI.

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

See Also:



1883
1884
1885
1886
1887
# File 'lib/redis.rb', line 1883

def discard
  synchronize do
    @client.call [:discard]
  end
end

#echo(value) ⇒ String

Echo the given string.

Parameters:

  • value (String)

Returns:

  • (String)


330
331
332
333
334
# File 'lib/redis.rb', line 330

def echo(value)
  synchronize do
    @client.call [:echo, value]
  end
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:



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

def exec
  synchronize do
    @client.call [:exec]
  end
end

#exists(key) ⇒ Boolean

Determine if a key exists.

Parameters:

  • key (String)

Returns:

  • (Boolean)


367
368
369
370
371
# File 'lib/redis.rb', line 367

def exists(key)
  synchronize do
    @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



1273
1274
1275
1276
1277
# File 'lib/redis.rb', line 1273

def expire(key, seconds)
  synchronize do
    @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



1305
1306
1307
1308
1309
# File 'lib/redis.rb', line 1305

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

#flushallString

Remove all keys from all databases.

Returns:

  • (String)

    OK



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

def flushall
  synchronize do
    @client.call [:flushall]
  end
end

#flushdbString

Remove all keys from the current database.

Returns:

  • (String)

    OK



121
122
123
124
125
# File 'lib/redis.rb', line 121

def flushdb
  synchronize do
    @client.call [:flushdb]
  end
end

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

Get the value of a key.

Parameters:

  • key (String)

Returns:

  • (String)


167
168
169
170
171
# File 'lib/redis.rb', line 167

def get(key)
  synchronize do
    @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



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

def getbit(key, offset)
  synchronize do
    @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



193
194
195
196
197
# File 'lib/redis.rb', line 193

def getrange(key, start, stop)
  synchronize do
    @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



205
206
207
208
209
# File 'lib/redis.rb', line 205

def getset(key, value)
  synchronize do
    @client.call [:getset, key, value]
  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



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

def hdel(key, field)
  synchronize do
    @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



1446
1447
1448
1449
1450
# File 'lib/redis.rb', line 1446

def hexists(key, field)
  synchronize do
    @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)


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

def hget(key, field)
  synchronize do
    @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>)


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

def hgetall(key)
  synchronize do
    @client.call [:hgetall, key] do |reply|
      if reply.kind_of?(Array)
        hash = Hash.new
        reply.each_slice(2) do |field, value|
          hash[field] = value
        end
        hash
      else
        reply
      end
    end
  end
end

#hincrby(key, field, increment) ⇒ Fixnum

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

Parameters:

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

Returns:

  • (Fixnum)

    value of the field after incrementing it



1435
1436
1437
1438
1439
# File 'lib/redis.rb', line 1435

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

#hkeys(key) ⇒ Array<String>

Get all the fields in a hash.

Parameters:

  • key (String)

Returns:

  • (Array<String>)


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

def hkeys(key)
  synchronize do
    @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



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

def hlen(key)
  synchronize do
    @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:



1378
1379
1380
1381
1382
# File 'lib/redis.rb', line 1378

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

#hmset(key, *attrs) ⇒ Object

Set one or more hash values.

Examples:

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

Parameters:

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

    array of fields and values

See Also:



1346
1347
1348
1349
1350
# File 'lib/redis.rb', line 1346

def hmset(key, *attrs)
  synchronize do
    @client.call [:hmset, key, *attrs]
  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



1317
1318
1319
1320
1321
# File 'lib/redis.rb', line 1317

def hset(key, field, value)
  synchronize do
    @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



1329
1330
1331
1332
1333
# File 'lib/redis.rb', line 1329

def hsetnx(key, field, value)
  synchronize do
    @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>)


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

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

#idObject



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

def id
  synchronize do
    @client.id
  end
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



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

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

#incrby(key, increment) ⇒ Fixnum

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

Examples:

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

Parameters:

  • key (String)
  • increment (Fixnum)

Returns:

  • (Fixnum)

    value after incrementing it



1695
1696
1697
1698
1699
# File 'lib/redis.rb', line 1695

def incrby(key, increment)
  synchronize do
    @client.call [:incrby, key, increment]
  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>)


82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
# File 'lib/redis.rb', line 82

def info(cmd = nil)
  synchronize do
    @client.call [:info, cmd].compact do |reply|
      if reply.kind_of?(String)
        reply = Hash[*reply.split(/:|\r\n/).grep(/^[^#]/)]

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

      reply
    end
  end
end

#inspectObject



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

def inspect
  synchronize do
    "#<Redis client v#{Redis::VERSION} connected to #{id} (Redis v#{info["redis_version"]})>"
  end
end

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

Find all keys matching the given pattern.

Parameters:

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

Returns:

  • (Array<String>)


305
306
307
308
309
310
311
312
313
314
315
# File 'lib/redis.rb', line 305

def keys(pattern = "*")
  synchronize do
    @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)


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

def lastsave
  synchronize do
    @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)


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

def lindex(key, index)
  synchronize do
    @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



426
427
428
429
430
# File 'lib/redis.rb', line 426

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

#llen(key) ⇒ Fixnum

Get the length of a list.

Parameters:

  • key (String)

Returns:

  • (Fixnum)


377
378
379
380
381
# File 'lib/redis.rb', line 377

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

#lpop(key) ⇒ String

Remove and get the first element in a list.

Parameters:

  • key (String)

Returns:

  • (String)


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

def lpop(key)
  synchronize do
    @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)

Returns:

  • (Fixnum)

    the length of the list after the push operation



486
487
488
489
490
# File 'lib/redis.rb', line 486

def lpush(key, value)
  synchronize do
    @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



497
498
499
500
501
# File 'lib/redis.rb', line 497

def lpushx(key, value)
  synchronize do
    @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>)


389
390
391
392
393
# File 'lib/redis.rb', line 389

def lrange(key, start, stop)
  synchronize do
    @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



453
454
455
456
457
# File 'lib/redis.rb', line 453

def lrem(key, count, value)
  synchronize do
    @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



438
439
440
441
442
# File 'lib/redis.rb', line 438

def lset(key, index, value)
  synchronize do
    @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



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

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

#mapped_hmget(key, *fields) ⇒ Hash

Get the values of all the given hash fields.

Examples:

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

Parameters:

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

    array of fields

Returns:

  • (Hash)

    a hash mapping the specified fields to their values

See Also:



1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
# File 'lib/redis.rb', line 1395

def mapped_hmget(key, *fields)
  hmget(key, *fields) do |reply|
    if reply.kind_of?(Array)
      hash = Hash.new
      fields.zip(reply).each do |field, value|
        hash[field] = value
      end
      hash
    else
      reply
    end
  end
end

#mapped_hmset(key, hash) ⇒ Object

Set one or more hash values.

Examples:

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

Parameters:

  • key (String)
  • hash (Hash)

    fields mapping to values

See Also:



1363
1364
1365
# File 'lib/redis.rb', line 1363

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

#mapped_mget(*keys) ⇒ Hash

Get the values of all the given keys.

Examples:

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

Parameters:

  • keys (Array<String>)

    array of keys

Returns:

  • (Hash)

    a hash mapping the specified keys to their values

See Also:



1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
# File 'lib/redis.rb', line 1602

def mapped_mget(*keys)
  mget(*keys) do |reply|
    if reply.kind_of?(Array)
      hash = Hash.new
      keys.zip(reply).each do |field, value|
        hash[field] = value
      end
      hash
    else
      reply
    end
  end
end

#mapped_mset(hash) ⇒ Object

Set one or more values.

Examples:

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

Parameters:

  • hash (Hash)

    keys mapping to values

See Also:



1558
1559
1560
# File 'lib/redis.rb', line 1558

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

#mapped_msetnx(hash) ⇒ Boolean

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

Examples:

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

Parameters:

  • hash (Hash)

    keys mapping to values

Returns:

  • (Boolean)

    whether or not all values were set

See Also:



1588
1589
1590
# File 'lib/redis.rb', line 1588

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:



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

def mget(*keys, &blk)
  synchronize do
    @client.call [:mget, *keys], &blk
  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



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

def monitor(&block)
  synchronize do
    @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
resis.get "foo"
  # => "bar"

Parameters:

  • key (String)
  • db (Fixnum)

Returns:

  • (Boolean)

    whether the key was moved or not



1219
1220
1221
1222
1223
# File 'lib/redis.rb', line 1219

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

#mset(*args) ⇒ Object

Set one or more values.

Examples:

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

Parameters:

  • args (Array<String>)

    array of keys and values

See Also:



1542
1543
1544
1545
1546
# File 'lib/redis.rb', line 1542

def mset(*args)
  synchronize do
    @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:



1572
1573
1574
1575
1576
# File 'lib/redis.rb', line 1572

def msetnx(*args)
  synchronize do
    @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:



1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
# File 'lib/redis.rb', line 1842

def multi
  synchronize do
    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



1470
1471
1472
1473
1474
# File 'lib/redis.rb', line 1470

def object(*args)
  synchronize do
    @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



1283
1284
1285
1286
1287
# File 'lib/redis.rb', line 1283

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

#pingString

Ping the server.

Returns:

  • (String)

    PONG



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

def ping
  synchronize do
    @client.call [:ping]
  end
end

#pipelinedObject



1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
# File 'lib/redis.rb', line 1775

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

#psubscribe(*channels, &block) ⇒ Object

Listen for messages published to channels matching the given patterns.



1926
1927
1928
1929
1930
# File 'lib/redis.rb', line 1926

def psubscribe(*channels, &block)
  synchronize do
    subscription(:psubscribe, channels, block)
  end
end

#publish(channel, message) ⇒ Object

Post a message to a channel.



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

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

#punsubscribe(*channels) ⇒ Object

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



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

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

#quitString

Close the connection.

Returns:

  • (String)

    OK



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

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

#randomkeyString

Return a random key from the keyspace.

Returns:

  • (String)


320
321
322
323
324
# File 'lib/redis.rb', line 320

def randomkey
  synchronize do
    @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



1251
1252
1253
1254
1255
# File 'lib/redis.rb', line 1251

def rename(old_name, new_name)
  synchronize do
    @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



1262
1263
1264
1265
1266
# File 'lib/redis.rb', line 1262

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

#rpop(key) ⇒ String

Remove and get the last element in a list.

Parameters:

  • key (String)

Returns:

  • (String)


507
508
509
510
511
# File 'lib/redis.rb', line 507

def rpop(key)
  synchronize do
    @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



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

def rpoplpush(source, destination)
  synchronize do
    @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



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

def rpush(key, value)
  synchronize do
    @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



475
476
477
478
479
# File 'lib/redis.rb', line 475

def rpushx(key, value)
  synchronize do
    @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



644
645
646
647
648
649
650
651
652
653
654
655
656
# File 'lib/redis.rb', line 644

def sadd(key, member)
  synchronize do
    @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)


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

def save
  synchronize do
    @client.call [:save]
  end
end

#scard(key) ⇒ Fixnum

Get the number of members in a set.

Parameters:

  • key (String)

Returns:

  • (Fixnum)


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

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



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

def sdiff(*keys)
  synchronize do
    @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



769
770
771
772
773
# File 'lib/redis.rb', line 769

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

#select(db) ⇒ String

Change the selected database for the current connection.

Parameters:

  • db (Fixnum)

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

Returns:

  • (String)

    OK



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

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

#set(key, value) ⇒ Object Also known as: []=

Set the string value of a key.

Parameters:

  • key (String)
  • value (String)


1488
1489
1490
1491
1492
# File 'lib/redis.rb', line 1488

def set(key, value)
  synchronize do
    @client.call [:set, key, value]
  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



1502
1503
1504
1505
1506
# File 'lib/redis.rb', line 1502

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

#setex(key, ttl, value) ⇒ Object

Set the value and expiration of a key.

Parameters:

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


1514
1515
1516
1517
1518
# File 'lib/redis.rb', line 1514

def setex(key, ttl, value)
  synchronize do
    @client.call [:setex, key, ttl, value]
  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



1230
1231
1232
1233
1234
# File 'lib/redis.rb', line 1230

def setnx(key, value)
  synchronize do
    @client.call [:setnx, key, value], &_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



1526
1527
1528
1529
1530
# File 'lib/redis.rb', line 1526

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

#shutdownObject

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



1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
# File 'lib/redis.rb', line 1755

def shutdown
  synchronize do
    @client.without_reconnect 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



716
717
718
719
720
# File 'lib/redis.rb', line 716

def sinter(*keys)
  synchronize do
    @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



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

def sinterstore(destination, *keys)
  synchronize do
    @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)


630
631
632
633
634
# File 'lib/redis.rb', line 630

def sismember(key, member)
  synchronize do
    @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.



1769
1770
1771
1772
1773
# File 'lib/redis.rb', line 1769

def slaveof(host, port)
  synchronize do
    @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



607
608
609
610
611
612
613
# File 'lib/redis.rb', line 607

def slowlog(subcommand, length=nil)
  synchronize do
    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>)


619
620
621
622
623
# File 'lib/redis.rb', line 619

def smembers(key)
  synchronize do
    @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)


686
687
688
689
690
# File 'lib/redis.rb', line 686

def smove(source, destination, member)
  synchronize do
    @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


1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
# File 'lib/redis.rb', line 1641

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.call [:sort, key, *args] do |reply|
      if get.size > 1
        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)


696
697
698
699
700
# File 'lib/redis.rb', line 696

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

#srandmember(key) ⇒ String

Get a random member from a set.

Parameters:

  • key (String)

Returns:

  • (String)


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

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



666
667
668
669
670
671
672
673
674
675
676
677
678
# File 'lib/redis.rb', line 666

def srem(key, member)
  synchronize do
    @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

#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



243
244
245
246
247
# File 'lib/redis.rb', line 243

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

#subscribe(*channels, &block) ⇒ Object

Listen for messages published to the given channels.



1919
1920
1921
1922
1923
# File 'lib/redis.rb', line 1919

def subscribe(*channels, &block)
  synchronize do
    subscription(:subscribe, channels, block)
  end
end

#subscribed?Boolean

Returns:

  • (Boolean)


1896
1897
1898
1899
1900
# File 'lib/redis.rb', line 1896

def subscribed?
  synchronize do
    @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



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

def sunion(*keys)
  synchronize do
    @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



748
749
750
751
752
# File 'lib/redis.rb', line 748

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

#syncObject

Internal command used for replication.



1477
1478
1479
1480
1481
# File 'lib/redis.rb', line 1477

def sync
  synchronize do
    @client.call [:sync]
  end
end

#ttl(key) ⇒ Fixnum

Get the time to live for a key.

Parameters:

  • key (String)

Returns:

  • (Fixnum)

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



1294
1295
1296
1297
1298
# File 'lib/redis.rb', line 1294

def ttl(key)
  synchronize do
    @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



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

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

#unsubscribe(*channels) ⇒ Object

Stop listening for messages posted to the given channels.



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

def unsubscribe(*channels)
  synchronize do
    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:



1806
1807
1808
1809
1810
# File 'lib/redis.rb', line 1806

def unwatch
  synchronize do
    @client.call [:unwatch]
  end
end

#watch(*keys) ⇒ String

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

Parameters:

  • keys (String, Array<String>)

    one or more keys to watch

Returns:

  • (String)

    OK

See Also:



1794
1795
1796
1797
1798
# File 'lib/redis.rb', line 1794

def watch(*keys)
  synchronize do
    @client.call [:watch, *keys]
  end
end

#without_reconnect(&block) ⇒ Object

Run code without the client reconnecting



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

def without_reconnect(&block)
  synchronize do
    @client.without_reconnect(&block)
  end
end

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

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

Examples:

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

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

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

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

Parameters:

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

Returns:

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


803
804
805
806
807
808
809
810
811
812
813
814
815
# File 'lib/redis.rb', line 803

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

#zcard(key) ⇒ Fixnum

Get the number of members in a sorted set.

Examples:

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

Parameters:

  • key (String)

Returns:

  • (Fixnum)


897
898
899
900
901
# File 'lib/redis.rb', line 897

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

#zcount(key, start, stop) ⇒ 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



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

def zcount(key, start, stop)
  synchronize do
    @client.call [:zcount, key, start, stop]
  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



881
882
883
884
885
886
887
# File 'lib/redis.rb', line 881

def zincrby(key, increment, member)
  synchronize do
    @client.call [:zincrby, key, increment, member] do |reply|
      Float(reply) if reply
    end
  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



1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
# File 'lib/redis.rb', line 1159

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


921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
# File 'lib/redis.rb', line 921

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

  with_scores = options[:with_scores] || options[:withscores]
  args << "WITHSCORES" if with_scores

  synchronize do
    @client.call [:zrange, key, start, stop, *args] do |reply|
      if with_scores
        if reply
          reply.each_slice(2).map do |member, score|
            [member, Float(score)]
          end
        end
      else
        reply
      end
    end
  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


1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
# File 'lib/redis.rb', line 1001

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

  with_scores = options[:with_scores] || options[:withscores]
  args.concat ["WITHSCORES"] if with_scores

  limit = options[:limit]
  args.concat ["LIMIT", *limit] if limit

  synchronize do
    @client.call [:zrangebyscore, key, min, max, *args] do |reply|
      if with_scores
        if reply
          reply.each_slice(2).map do |member, score|
            [member, Float(score)]
          end
        end
      else
        reply
      end
    end
  end
end

#zrank(key, member) ⇒ Fixnum

Determine the index of a member in a sorted set.

Parameters:

  • key (String)
  • member (String)

Returns:

  • (Fixnum)


853
854
855
856
857
# File 'lib/redis.rb', line 853

def zrank(key, member)
  synchronize do
    @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


834
835
836
837
838
839
840
841
842
843
844
845
846
# File 'lib/redis.rb', line 834

def zrem(key, member)
  synchronize do
    @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



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

def zremrangebyrank(key, start, stop)
  synchronize do
    @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



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

def zremrangebyscore(key, min, max)
  synchronize do
    @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:



953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
# File 'lib/redis.rb', line 953

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

  with_scores = options[:with_scores] || options[:withscores]
  args << "WITHSCORES" if with_scores

  synchronize do
    @client.call [:zrevrange, key, start, stop, *args] do |reply|
      if with_scores
        if reply
          reply.each_slice(2).map do |member, score|
            [member, Float(score)]
          end
        end
      else
        reply
      end
    end
  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:



1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
# File 'lib/redis.rb', line 1039

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

  with_scores = options[:with_scores] || options[:withscores]
  args.concat ["WITHSCORES"] if with_scores

  limit = options[:limit]
  args.concat ["LIMIT", *limit] if limit

  synchronize do
    @client.call [:zrevrangebyscore, key, max, min, *args] do |reply|
      if with_scores
        if reply
          reply.each_slice(2).map do |member, score|
            [member, Float(score)]
          end
        end
      else
        reply
      end
    end
  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)


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

def zrevrank(key, member)
  synchronize do
    @client.call [:zrevrank, key, member]
  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



1137
1138
1139
1140
1141
1142
1143
# File 'lib/redis.rb', line 1137

def zscore(key, member)
  synchronize do
    @client.call [:zscore, key, member] do |reply|
      Float(reply) if reply
    end
  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



1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
# File 'lib/redis.rb', line 1186

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.call [:zunionstore, destination, keys.size, *(keys + args)]
  end
end