Module: Valkey::Commands::GenericCommands

Included in:
Valkey::Commands
Defined in:
lib/valkey/commands/generic_commands.rb

Overview

this module contains generic commands that are not specific to any data type

See Also:

Instance Method Summary collapse

Instance Method Details

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



448
449
450
451
452
453
454
455
456
457
 
# File 'lib/valkey/commands/generic_commands.rb', line 448

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

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

Copy a value to a key in another database

valkey.set "foo", "value"
  # => "OK"
valkey.copy "foo", "bar", db: 2
  # => true
valkey.select 2
  # => "OK"
valkey.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



333
334
335
336
337
338
339
 
# File 'lib/valkey/commands/generic_commands.rb', line 333

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

  send_command(RequestType::COPY, args)
end

#del(*keys) ⇒ Integer

Delete one or more keys.

Parameters:

  • keys (String, Array<String>)

Returns:

  • (Integer) —

    number of keys that were deleted



254
255
256
257
258
259
 
# File 'lib/valkey/commands/generic_commands.rb', line 254

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

  send_command(RequestType::DEL, keys)
end

#dump(key) ⇒ String

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

Parameters:

  • key (String)

Returns:

  • (String) —

    serialized_value



205
206
207
 
# File 'lib/valkey/commands/generic_commands.rb', line 205

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

#exists(*keys) ⇒ Integer

Determine how many of the keys exists.

Parameters:

  • keys (String, Array<String>)

Returns:

  • (Integer) 


273
274
275
 
# File 'lib/valkey/commands/generic_commands.rb', line 273

def exists(*keys)
  send_command(RequestType::EXISTS, keys.flatten)
end

#exists?(*keys) ⇒ Boolean

Determine if any of the keys exists.

Parameters:

  • keys (String, Array<String>)

Returns:

  • (Boolean) 


281
282
283
 
# File 'lib/valkey/commands/generic_commands.rb', line 281

def exists?(*keys)
  send_command(RequestType::EXISTS, keys.flatten, &:positive?)
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



84
85
86
87
88
89
90
91
92
 
# File 'lib/valkey/commands/generic_commands.rb', line 84

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

  send_command(RequestType::EXPIRE, args)
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



104
105
106
107
108
109
110
111
112
 
# File 'lib/valkey/commands/generic_commands.rb', line 104

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

  send_command(RequestType::EXPIRE_AT, args)
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



118
119
120
 
# File 'lib/valkey/commands/generic_commands.rb', line 118

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

#move(key, db) ⇒ Boolean

Move a key to another database.

Examples:

Move a key to another database

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

Parameters:

  • key (String)
  • db (Integer)

Returns:

  • (Boolean) —

    whether the key was moved or not



304
305
306
 
# File 'lib/valkey/commands/generic_commands.rb', line 304

def move(key, db)
  send_command(RequestType::MOVE, [key, db])
end

#object(subcommand, *args) ⇒ Object 



341
342
343
344
345
346
347
348
349
350
 
# File 'lib/valkey/commands/generic_commands.rb', line 341

def object(subcommand, *args)
  map = {
    refcount: RequestType::OBJECT_REF_COUNT,
    encoding: RequestType::OBJECT_ENCODING,
    idletime: RequestType::OBJECT_IDLE_TIME,
    freq: RequestType::OBJECT_FREQ
  }

  send_command(map[subcommand.to_sym], args.flatten)
end

#persist(key) ⇒ Boolean

Remove the expiration from a key.

Parameters:

  • key (String)

Returns:

  • (Boolean) —

    whether the timeout was removed or not



70
71
72
 
# File 'lib/valkey/commands/generic_commands.rb', line 70

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



148
149
150
151
152
153
154
155
156
 
# File 'lib/valkey/commands/generic_commands.rb', line 148

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

  send_command(RequestType::PEXPIRE, args)
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



168
169
170
171
172
173
174
175
176
 
# File 'lib/valkey/commands/generic_commands.rb', line 168

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

  send_command(RequestType::PEXPIRE_AT, args)
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



182
183
184
 
# File 'lib/valkey/commands/generic_commands.rb', line 182

def pexpiretime(key)
  send_command(RequestType::PEXPIRE_TIME, [key])
end

#pttl(key) ⇒ Integer

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

In valkey 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 valkey 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



197
198
199
 
# File 'lib/valkey/commands/generic_commands.rb', line 197

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

#randomkey ⇒ String

Return a random key from the keyspace.

Returns:

  • (String) 


355
356
357
 
# File 'lib/valkey/commands/generic_commands.rb', line 355

def randomkey
  send_command(RequestType::RANDOM_KEY)
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`



364
365
366
 
# File 'lib/valkey/commands/generic_commands.rb', line 364

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



373
374
375
 
# File 'lib/valkey/commands/generic_commands.rb', line 373

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

  • (valkey::CommandError) 


218
219
220
221
222
223
 
# File 'lib/valkey/commands/generic_commands.rb', line 218

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

  send_command(RequestType::RESTORE, args)
end

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

Scan the keyspace

Examples:

Retrieve the first batch of keys

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

Retrieve a batch of keys matching a pattern

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

Retrieve a batch of keys of a certain type

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



30
31
32
 
# File 'lib/valkey/commands/generic_commands.rb', line 30

def scan(cursor, **options)
  _scan(RequestType::SCAN, cursor, [], **options)
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”

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

Store an alphabetically descending list in “target”

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



402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
 
# File 'lib/valkey/commands/generic_commands.rb', line 402

def sort(key, by: nil, limit: nil, get: nil, order: nil, store: nil)
  args = [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(RequestType::SORT, args) do |reply|
    if get.size > 1 && !store
      reply.each_slice(get.size).to_a if reply
    else
      reply
    end
  end
end

#touch(*keys) ⇒ Object 



428
429
430
 
# File 'lib/valkey/commands/generic_commands.rb', line 428

def touch(*keys)
  send_command(RequestType::TOUCH, keys.flatten)
end

#ttl(key) ⇒ Integer

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

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



134
135
136
 
# File 'lib/valkey/commands/generic_commands.rb', line 134

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

#type(key) ⇒ String

Determine the type stored at key.

Parameters:

  • key (String)

Returns:

  • (String) —

    ‘string`, `list`, `set`, `zset`, `hash` or `none`



444
445
446
 
# File 'lib/valkey/commands/generic_commands.rb', line 444

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

#unlink(*keys) ⇒ Integer

Unlink one or more keys.

Parameters:

  • keys (String, Array<String>)

Returns:

  • (Integer) —

    number of keys that were unlinked



265
266
267
 
# File 'lib/valkey/commands/generic_commands.rb', line 265

def unlink(*keys)
  send_command(RequestType::UNLINK, keys.flatten)
end

#wait(*keys) ⇒ Object 



432
433
434
 
# File 'lib/valkey/commands/generic_commands.rb', line 432

def wait(*keys)
  send_command(RequestType::WAIT, keys.flatten)
end

#waitof(*keys) ⇒ Object 



436
437
438
 
# File 'lib/valkey/commands/generic_commands.rb', line 436

def waitof(*keys)
  send_command(RequestType::WAIT_AOF, keys.flatten)
end