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



343
344
345
346
347
348
349
 
# File 'lib/redis/commands/keys.rb', line 343

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



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

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



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

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) 


267
268
269
 
# File 'lib/redis/commands/keys.rb', line 267

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) 


275
276
277
278
279
 
# File 'lib/redis/commands/keys.rb', line 275

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

#expiretime(key) ⇒ Integer

Get a key’s expiry time specified as number of seconds from UNIX Epoch

Parameters:

  • key (String)

Returns:

  • (Integer) —

    expiry time specified as number of seconds from UNIX Epoch



112
113
114
 
# File 'lib/redis/commands/keys.rb', line 112

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

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

Find all keys matching the given pattern.

Parameters:

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

Returns:

  • (Array<String>) 


285
286
287
288
289
290
291
292
293
 
# File 'lib/redis/commands/keys.rb', line 285

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”`



230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/redis/commands/keys.rb', line 230

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



314
315
316
 
# File 'lib/redis/commands/keys.rb', line 314

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

#object(*args) ⇒ Object 



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

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



142
143
144
145
146
147
148
149
150
 
# File 'lib/redis/commands/keys.rb', line 142

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



162
163
164
165
166
167
168
169
170
 
# File 'lib/redis/commands/keys.rb', line 162

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

#pexpiretime(key) ⇒ Integer

Get a key’s expiry time specified as number of milliseconds from UNIX Epoch

Parameters:

  • key (String)

Returns:

  • (Integer) —

    expiry time specified as number of milliseconds from UNIX Epoch



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

def pexpiretime(key)
  send_command([:pexpiretime, key])
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



191
192
193
 
# File 'lib/redis/commands/keys.rb', line 191

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

#randomkey ⇒ String

Return a random key from the keyspace.

Returns:

  • (String) 


358
359
360
 
# File 'lib/redis/commands/keys.rb', line 358

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`



367
368
369
 
# File 'lib/redis/commands/keys.rb', line 367

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



376
377
378
 
# File 'lib/redis/commands/keys.rb', line 376

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:



212
213
214
215
216
217
 
# File 'lib/redis/commands/keys.rb', line 212

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



405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
 
# File 'lib/redis/commands/keys.rb', line 405

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.



128
129
130
 
# File 'lib/redis/commands/keys.rb', line 128

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`



435
436
437
 
# File 'lib/redis/commands/keys.rb', line 435

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



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

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