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 



513
514
515
516
517
518
519
520
521
522
 
# File 'lib/valkey/commands/generic_commands.rb', line 513

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"



368
369
370
371
372
373
374
 
# File 'lib/valkey/commands/generic_commands.rb', line 368

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.



289
290
291
292
293
294
 
# File 'lib/valkey/commands/generic_commands.rb', line 289

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.



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.



308
309
310
 
# File 'lib/valkey/commands/generic_commands.rb', line 308

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

#exists?(*keys) ⇒ Boolean

Determine if any of the keys exists.



316
317
318
 
# File 'lib/valkey/commands/generic_commands.rb', line 316

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.



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.



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



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

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

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

Find all keys matching the given pattern.

Examples:

Find all keys

valkey.keys
  # => ["key1", "key2", ...]

Find keys matching a pattern

valkey.keys("user:*")
  # => ["user:1", "user:2"]

See Also:



275
276
277
278
279
280
281
282
283
 
# File 'lib/valkey/commands/generic_commands.rb', line 275

def keys(pattern = "*")
  send_command(RequestType::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.

Examples:

Migrate a single key

valkey.migrate("mykey", host: "127.0.0.1", port: 6380)
  # => "OK"

Migrate with copy and replace

valkey.migrate("mykey", host: "127.0.0.1", port: 6380, copy: true, replace: true)
  # => "OK"

Migrate multiple keys

valkey.migrate(["key1", "key2"], host: "127.0.0.1", port: 6380)
  # => "OK"

See Also:



248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/valkey/commands/generic_commands.rb', line 248

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

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



339
340
341
 
# File 'lib/valkey/commands/generic_commands.rb', line 339

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

#object(subcommand, *args) ⇒ Object 



376
377
378
379
380
381
382
383
384
385
 
# File 'lib/valkey/commands/generic_commands.rb', line 376

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.



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.



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.



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



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.



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.



390
391
392
 
# File 'lib/valkey/commands/generic_commands.rb', line 390

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.



399
400
401
 
# File 'lib/valkey/commands/generic_commands.rb', line 399

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.



408
409
410
 
# File 'lib/valkey/commands/generic_commands.rb', line 408

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.

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"]]



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



437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
 
# File 'lib/valkey/commands/generic_commands.rb', line 437

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 



463
464
465
 
# File 'lib/valkey/commands/generic_commands.rb', line 463

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.



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.



509
510
511
 
# File 'lib/valkey/commands/generic_commands.rb', line 509

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

#unlink(*keys) ⇒ Integer

Unlink one or more keys.



300
301
302
 
# File 'lib/valkey/commands/generic_commands.rb', line 300

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

#wait(numreplicas, timeout) ⇒ Integer

Block until all the previous write commands are successfully transferred and acknowledged by at least the specified number of replicas.

Examples:

Wait for 1 replica with 1 second timeout

valkey.wait(1, 1000)
  # => 1

See Also:



479
480
481
 
# File 'lib/valkey/commands/generic_commands.rb', line 479

def wait(numreplicas, timeout)
  send_command(RequestType::WAIT, [numreplicas.to_s, timeout.to_s])
end

#waitaof(numlocal, numreplicas, timeout) ⇒ Array<Integer>

Block until all previous write commands are fsynced to the AOF of the local server and/or at least the specified number of replicas.

Examples:

Wait for local AOF fsync with no timeout

valkey.waitaof(1, 0, 0)
  # => [1, 0]

Wait for 1 replica fsync with 1 second timeout

valkey.waitaof(0, 1, 1000)
  # => [0, 0]

See Also:



501
502
503
 
# File 'lib/valkey/commands/generic_commands.rb', line 501

def waitaof(numlocal, numreplicas, timeout)
  send_command(RequestType::WAIT_AOF, [numlocal.to_s, numreplicas.to_s, timeout.to_s])
end