Module: Redis::Commands::Keys

Included in:
Redis::Commands
Defined in:
lib/redis/commands/keys.rb

Instance Method Summary collapse

Instance Method Details

#copy(source, destination, db: nil, replace: false) ⇒ Boolean

Copy a value from one key to another.

Examples:

Copy a value to another key

redis.set "foo", "value"
  # => "OK"
redis.copy "foo", "bar"
  # => true
redis.get "bar"
  # => "value"

Copy a value to a key in another database

redis.set "foo", "value"
  # => "OK"
redis.copy "foo", "bar", db: 2
  # => true
redis.select 2
  # => "OK"
redis.get "bar"
  # => "value"

Parameters:

  • source (String)
  • destination (String)
  • db (Integer) (defaults to: nil)
  • replace (Boolean) (defaults to: false) —

    removes the destination key before copying value to it

Returns:

  • (Boolean) —

    whether the key was copied or not



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

def copy(source, destination, db: nil, replace: false)
  command = [:copy, source, destination]
  command << "DB" << db if db
  command << "REPLACE" if replace

  send_command(command, &Boolify)
end

#del(*keys) ⇒ Integer

Delete one or more keys.

Parameters:

  • keys (String, Array<String>)

Returns:

  • (Integer) —

    number of keys that were deleted



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

def del(*keys)
  keys.flatten!(1)
  return 0 if keys.empty?

  send_command([:del] + keys)
end

#dump(key) ⇒ String

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

Parameters:

  • key (String)

Returns:

  • (String) —

    serialized_value



183
184
185
 
# File 'lib/redis/commands/keys.rb', line 183

def dump(key)
  send_command([:dump, key])
end

#exists(*keys) ⇒ Integer

Determine how many of the keys exists.

Parameters:

  • keys (String, Array<String>)

Returns:

  • (Integer) 


251
252
253
 
# File 'lib/redis/commands/keys.rb', line 251

def exists(*keys)
  send_command([:exists, *keys])
end

#exists?(*keys) ⇒ Boolean

Determine if any of the keys exists.

Parameters:

  • keys (String, Array<String>)

Returns:

  • (Boolean) 


259
260
261
262
263
 
# File 'lib/redis/commands/keys.rb', line 259

def exists?(*keys)
  send_command([:exists, *keys]) do |value|
    value > 0
  end
end

#expire(key, seconds, nx: nil, xx: nil, gt: nil, lt: nil) ⇒ Boolean

Set a key's time to live in seconds.

Parameters:

  • key (String)
  • seconds (Integer) —

    time to live

  • options (Hash) —
    • :nx => true: Set expiry only when the key has no expiry.
    • :xx => true: Set expiry only when the key has an existing expiry.
    • :gt => true: Set expiry only when the new expiry is greater than current one.
    • :lt => true: Set expiry only when the new expiry is less than current one.

Returns:

  • (Boolean) —

    whether the timeout was set or not



78
79
80
81
82
83
84
85
86
 
# File 'lib/redis/commands/keys.rb', line 78

def expire(key, seconds, nx: nil, xx: nil, gt: nil, lt: nil)
  args = [:expire, key, Integer(seconds)]
  args << "NX" if nx
  args << "XX" if xx
  args << "GT" if gt
  args << "LT" if lt

  send_command(args, &Boolify)
end

#expireat(key, unix_time, nx: nil, xx: nil, gt: nil, lt: nil) ⇒ Boolean

Set the expiration for a key as a UNIX timestamp.

Parameters:

  • key (String)
  • unix_time (Integer) —

    expiry time specified as a UNIX timestamp

  • options (Hash) —
    • :nx => true: Set expiry only when the key has no expiry.
    • :xx => true: Set expiry only when the key has an existing expiry.
    • :gt => true: Set expiry only when the new expiry is greater than current one.
    • :lt => true: Set expiry only when the new expiry is less than current one.

Returns:

  • (Boolean) —

    whether the timeout was set or not



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

def expireat(key, unix_time, nx: nil, xx: nil, gt: nil, lt: nil)
  args = [:expireat, key, Integer(unix_time)]
  args << "NX" if nx
  args << "XX" if xx
  args << "GT" if gt
  args << "LT" if lt

  send_command(args, &Boolify)
end

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

Find all keys matching the given pattern.

Parameters:

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

Returns:

  • (Array<String>) 


269
270
271
272
273
274
275
276
277
 
# File 'lib/redis/commands/keys.rb', line 269

def keys(pattern = "*")
  send_command([:keys, pattern]) do |reply|
    if reply.is_a?(String)
      reply.split(" ")
    else
      reply
    end
  end
end

#migrate(key, options) ⇒ String

Transfer a key from the connected instance to another instance.

Parameters:

  • key (String, Array<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)
    • :copy => Boolean: Do not remove the key from the local instance.
    • :replace => Boolean: Replace existing key on the remote instance.

Returns:

  • (String) —

    "OK"



214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/redis/commands/keys.rb', line 214

def migrate(key, options)
  args = [:migrate]
  args << (options[:host] || raise(':host not specified'))
  args << (options[:port] || raise(':port not specified'))
  args << (key.is_a?(String) ? key : '')
  args << (options[:db] || @client.db).to_i
  args << (options[:timeout] || @client.timeout).to_i
  args << 'COPY' if options[:copy]
  args << 'REPLACE' if options[:replace]
  args += ['KEYS', *key] if key.is_a?(Array)

  send_command(args)
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 (Integer)

Returns:

  • (Boolean) —

    whether the key was moved or not



298
299
300
 
# File 'lib/redis/commands/keys.rb', line 298

def move(key, db)
  send_command([:move, key, db], &Boolify)
end

#object(*args) ⇒ Object 



335
336
337
 
# File 'lib/redis/commands/keys.rb', line 335

def object(*args)
  send_command([:object] + args)
end

#persist(key) ⇒ Boolean

Remove the expiration from a key.

Parameters:

  • key (String)

Returns:

  • (Boolean) —

    whether the timeout was removed or not



64
65
66
 
# File 'lib/redis/commands/keys.rb', line 64

def persist(key)
  send_command([:persist, key], &Boolify)
end

#pexpire(key, milliseconds, nx: nil, xx: nil, gt: nil, lt: nil) ⇒ Boolean

Set a key's time to live in milliseconds.

Parameters:

  • key (String)
  • milliseconds (Integer) —

    time to live

  • options (Hash) —
    • :nx => true: Set expiry only when the key has no expiry.
    • :xx => true: Set expiry only when the key has an existing expiry.
    • :gt => true: Set expiry only when the new expiry is greater than current one.
    • :lt => true: Set expiry only when the new expiry is less than current one.

Returns:

  • (Boolean) —

    whether the timeout was set or not



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

def pexpire(key, milliseconds, nx: nil, xx: nil, gt: nil, lt: nil)
  args = [:pexpire, key, Integer(milliseconds)]
  args << "NX" if nx
  args << "XX" if xx
  args << "GT" if gt
  args << "LT" if lt

  send_command(args, &Boolify)
end

#pexpireat(key, ms_unix_time, nx: nil, xx: nil, gt: nil, lt: nil) ⇒ Boolean

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

Parameters:

  • key (String)
  • ms_unix_time (Integer) —

    expiry time specified as number of milliseconds from UNIX Epoch.

  • options (Hash) —
    • :nx => true: Set expiry only when the key has no expiry.
    • :xx => true: Set expiry only when the key has an existing expiry.
    • :gt => true: Set expiry only when the new expiry is greater than current one.
    • :lt => true: Set expiry only when the new expiry is less than current one.

Returns:

  • (Boolean) —

    whether the timeout was set or not



154
155
156
157
158
159
160
161
162
 
# File 'lib/redis/commands/keys.rb', line 154

def pexpireat(key, ms_unix_time, nx: nil, xx: nil, gt: nil, lt: nil)
  args = [:pexpireat, key, Integer(ms_unix_time)]
  args << "NX" if nx
  args << "XX" if xx
  args << "GT" if gt
  args << "LT" if lt

  send_command(args, &Boolify)
end

#pttl(key) ⇒ Integer

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:

  • (Integer) —

    remaining time to live in milliseconds



175
176
177
 
# File 'lib/redis/commands/keys.rb', line 175

def pttl(key)
  send_command([:pttl, key])
end

#randomkey ⇒ String

Return a random key from the keyspace.

Returns:

  • (String) 


342
343
344
 
# File 'lib/redis/commands/keys.rb', line 342

def randomkey
  send_command([:randomkey])
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



351
352
353
 
# File 'lib/redis/commands/keys.rb', line 351

def rename(old_name, new_name)
  send_command([:rename, old_name, new_name])
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



360
361
362
 
# File 'lib/redis/commands/keys.rb', line 360

def renamenx(old_name, new_name)
  send_command([:renamenx, old_name, new_name], &Boolify)
end

#restore(key, ttl, serialized_value, replace: nil) ⇒ String

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

Parameters:

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

Returns:

  • (String) —

    "OK"

Raises:



196
197
198
199
200
201
 
# File 'lib/redis/commands/keys.rb', line 196

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

  send_command(args)
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"]]

Retrieve a batch of keys of a certain type

redis.scan(92, :type => "zset")
  # => ["173", ["sortedset:14", "sortedset:78"]]

Parameters:

  • cursor (String, Integer) —

    the cursor of the iteration

  • options (Hash) —
    • :match => String: only return keys matching the pattern
    • :count => Integer: return count keys at most per iteration
    • :type => String: return keys only of the given type

Returns:

  • (String, Array<String>) —

    the next cursor and all found keys



25
26
27
 
# File 'lib/redis/commands/keys.rb', line 25

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

Execute block for each key of a type

redis.scan_each(:type => "hash") {|key| puts redis.type(key)}
  # => "hash"
  # => "hash"

Parameters:

  • options (Hash) —
    • :match => String: only return keys matching the pattern
    • :count => Integer: return count keys at most per iteration
    • :type => String: return keys only of the given type

Returns:

  • (Enumerator) —

    an enumerator for all found keys



49
50
51
52
53
54
55
56
57
58
 
# File 'lib/redis/commands/keys.rb', line 49

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

#sort(key, by: nil, limit: nil, get: nil, order: nil, store: nil) ⇒ 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) —
    • :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>>, Integer) —
    • 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


389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
 
# File 'lib/redis/commands/keys.rb', line 389

def sort(key, by: nil, limit: nil, get: nil, order: nil, store: nil)
  args = [:sort, key]
  args << "BY" << by if by

  if limit
    args << "LIMIT"
    args.concat(limit)
  end

  get = Array(get)
  get.each do |item|
    args << "GET" << item
  end

  args.concat(order.split(" ")) if order
  args << "STORE" << store if store

  send_command(args) do |reply|
    if get.size > 1 && !store
      reply.each_slice(get.size).to_a if reply
    else
      reply
    end
  end
end

#ttl(key) ⇒ Integer

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:

  • (Integer) —

    remaining time to live in seconds.



120
121
122
 
# File 'lib/redis/commands/keys.rb', line 120

def ttl(key)
  send_command([:ttl, key])
end

#type(key) ⇒ String

Determine the type stored at key.

Parameters:

  • key (String)

Returns:

  • (String) —

    string, list, set, zset, hash or none



419
420
421
 
# File 'lib/redis/commands/keys.rb', line 419

def type(key)
  send_command([:type, key])
end

#unlink(*keys) ⇒ Integer

Unlink one or more keys.

Parameters:

  • keys (String, Array<String>)

Returns:

  • (Integer) —

    number of keys that were unlinked



243
244
245
 
# File 'lib/redis/commands/keys.rb', line 243

def unlink(*keys)
  send_command([:unlink] + keys)
end