Module: Redis::Commands::Keys

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Included In: `::Redis`, `::Redis::Commands`, `::Redis::MultiConnection`, `::Redis::PipelinedConnection`
Defined in:	lib/redis/commands/keys.rb

Instance Method Summary

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

Copy a value from one key to another.
#del(*keys) ⇒ Integer

Delete one or more keys.
#dump(key) ⇒ String

Return a serialized version of the value stored at a key.
#exists(*keys) ⇒ Integer

Determine how many of the keys exists.
#exists?(*keys) ⇒ Boolean

Determine if any of the keys exists.
#expire(key, seconds, nx: nil, xx: nil, gt: nil, lt: nil) ⇒ Boolean

Set a key's time to live in seconds.
#expireat(key, unix_time, nx: nil, xx: nil, gt: nil, lt: nil) ⇒ Boolean

Set the expiration for a key as a UNIX timestamp.
#expiretime(key) ⇒ Integer

Get a key's expiry time specified as number of seconds from UNIX Epoch.
#keys(pattern = "*") ⇒ Array<String>

Find all keys matching the given pattern.
#migrate(key, options) ⇒ String

Transfer a key from the connected instance to another instance.
#move(key, db) ⇒ Boolean

Move a key to another database.
#object(*args)
#persist(key) ⇒ Boolean

Remove the expiration from a key.
#pexpire(key, milliseconds, nx: nil, xx: nil, gt: nil, lt: nil) ⇒ Boolean

Set a key's time to live in milliseconds.
#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.
#pexpiretime(key) ⇒ Integer

Get a key's expiry time specified as number of milliseconds from UNIX Epoch.
#pttl(key) ⇒ Integer

Get the time to live (in milliseconds) for a key.
#randomkey ⇒ String

Return a random key from the keyspace.
#rename(old_name, new_name) ⇒ String

Rename a key.
#renamenx(old_name, new_name) ⇒ Boolean

Rename a key, only if the new key does not exist.
#restore(key, ttl, serialized_value, replace: nil) ⇒ String

Create a key using the serialized value, previously obtained using DUMP.
#scan(cursor, **options) ⇒ String⁺

Scan the keyspace.
#scan_each(**options, &block) ⇒ Enumerator

Scan the keyspace.
#sort(key, by: nil, limit: nil, get: nil, order: nil, store: nil) ⇒ Array<String>, ...

Sort the elements in a list, set or sorted set.
#ttl(key) ⇒ Integer

Get the time to live (in seconds) for a key.
#type(key) ⇒ String

Determine the type stored at key.
#unlink(*keys) ⇒ Integer

Unlink one or more keys.
#_scan(command, cursor, args, match: nil, count: nil, type: nil, &block) private

Instance Method Details

#_scan(command, cursor, args, match: nil, count: nil, type: nil, &block) (private)

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 447


def _scan(command, cursor, args, match: nil, count: nil, type: nil, &block)
  # SSCAN/ZSCAN/HSCAN already prepend the key to +args+.

  args << cursor
  args << "MATCH" << match if match
  args << "COUNT" << Integer(count) if count
  args << "TYPE" << type if type

  send_command([command] + args, &block)
end

#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)
replace (Boolean) —
removes the destination key before copying value to it

Returns:

(Boolean) —
whether the key was copied or not

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 349


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

[ GitHub ]

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


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 203


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

#exists(*keys) ⇒ `Integer`

Determine how many of the keys exists.

Parameters:

keys (String, Array<String>)

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 271


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

#exists?(*keys) ⇒ `Boolean`

Determine if any of the keys exists.

Parameters:

keys (String, Array<String>)

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 279


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 82


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 102


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 116


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

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

Find all keys matching the given pattern.

See the Redis Server KEYS documentation for further details

Parameters:

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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 291


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"

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 234


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 320


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

#object(*args)

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 357


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 68


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 146


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 166


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 180


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 195


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

#randomkey ⇒ `String`

Return a random key from the keyspace.

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 364


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 373


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 382


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:

(Redis::CommandError)

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 216


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

See the Redis Server SCAN documentation for further details

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

[ GitHub ]

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


def scan(cursor, **options)
  _scan(:scan, cursor, [], **options)
end

#scan_each(**options, &block) ⇒ `Enumerator`

Scan the keyspace

See the Redis Server SCAN documentation for further details

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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 53


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 411


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.

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 132


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 441


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

[ GitHub ]

# File 'lib/redis/commands/keys.rb', line 263


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

Module: Redis::Commands::Keys

Instance Method Summary

Instance Method Details

#_scan(command, cursor, args, match: nil, count: nil, type: nil, &block) (private)

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

#del(*keys) ⇒ Integer

#dump(key) ⇒ String

#exists(*keys) ⇒ Integer

#exists?(*keys) ⇒ Boolean

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

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

#expiretime(key) ⇒ Integer

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

#migrate(key, options) ⇒ String

#move(key, db) ⇒ Boolean

#object(*args)

#persist(key) ⇒ Boolean

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

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

#pexpiretime(key) ⇒ Integer

#pttl(key) ⇒ Integer

#randomkey ⇒ String

#rename(old_name, new_name) ⇒ String

#renamenx(old_name, new_name) ⇒ Boolean

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

#scan(cursor, **options) ⇒ String+

#scan_each(**options, &block) ⇒ Enumerator

#sort(key, by: nil, limit: nil, get: nil, order: nil, store: nil) ⇒ Array<String>, ...

#ttl(key) ⇒ Integer

#type(key) ⇒ String

#unlink(*keys) ⇒ Integer

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

#del(*keys) ⇒ `Integer`

#dump(key) ⇒ `String`

#exists(*keys) ⇒ `Integer`

#exists?(*keys) ⇒ `Boolean`

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

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

#expiretime(key) ⇒ `Integer`

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

#migrate(key, options) ⇒ `String`

#move(key, db) ⇒ `Boolean`

#persist(key) ⇒ `Boolean`

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

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

#pexpiretime(key) ⇒ `Integer`

#pttl(key) ⇒ `Integer`

#randomkey ⇒ `String`

#rename(old_name, new_name) ⇒ `String`

#renamenx(old_name, new_name) ⇒ `Boolean`

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

#scan(cursor, **options) ⇒ `String`⁺

#scan_each(**options, &block) ⇒ `Enumerator`

#sort(key, by: nil, limit: nil, get: nil, order: nil, store: nil) ⇒ `Array`<`String`>, ...

#ttl(key) ⇒ `Integer`

#type(key) ⇒ `String`

#unlink(*keys) ⇒ `Integer`