Module: Valkey::Commands::FunctionCommands

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

Overview

This module contains commands related to Valkey Functions.

See Also:

Instance Method Summary collapse

Instance Method Details

#fcall(function, keys: [], args: []) ⇒ Object

Invoke a function.

Examples:

Call a function

valkey.fcall("myfunc", keys: ["key1"], args: ["arg1"])
  # => <function result>

Call a function without keys

valkey.fcall("myfunc", args: ["arg1", "arg2"])
  # => <function result>

Parameters:

  • function (String) —

    the function name

  • keys (Array<String>) (defaults to: []) —

    the keys to pass to the function

  • args (Array<String>) (defaults to: []) —

    the arguments to pass to the function

Returns:

  • (Object) —

    the function result

See Also:



189
190
191
192
 
# File 'lib/valkey/commands/function_commands.rb', line 189

def fcall(function, keys: [], args: [])
  command_args = [function, keys.size] + keys + args
  send_command(RequestType::FCALL, command_args)
end

#fcall_ro(function, keys: [], args: []) ⇒ Object

Invoke a read-only function.

Examples:

Call a read-only function

valkey.fcall_ro("myfunc", keys: ["key1"], args: ["arg1"])
  # => <function result>

Parameters:

  • function (String) —

    the function name

  • keys (Array<String>) (defaults to: []) —

    the keys to pass to the function

  • args (Array<String>) (defaults to: []) —

    the arguments to pass to the function

Returns:

  • (Object) —

    the function result

See Also:



206
207
208
209
 
# File 'lib/valkey/commands/function_commands.rb', line 206

def fcall_ro(function, keys: [], args: [])
  command_args = [function, keys.size] + keys + args
  send_command(RequestType::FCALL_READ_ONLY, command_args)
end

#function(subcommand, *args, **options) ⇒ Object

Control function registry (convenience method).

Examples:

Delete a library

valkey.function(:delete, "mylib")
  # => "OK"

Dump all libraries

valkey.function(:dump)
  # => <binary string>

Flush all libraries

valkey.function(:flush)
  # => "OK"

Kill a running function

valkey.function(:kill)
  # => "OK"

List all libraries

valkey.function(:list)
  # => [...]

Load a library

valkey.function(:load, code)
  # => "mylib"

Restore libraries

valkey.function(:restore, payload)
  # => "OK"

Get function stats

valkey.function(:stats)
  # => {...}

Parameters:

  • subcommand (String, Symbol) —

    the subcommand (delete, dump, flush, kill, list, load, restore, stats)

  • args (Array) —

    arguments for the subcommand

  • options (Hash) —

    options for the subcommand

Returns:

  • (Object) —

    depends on subcommand



242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/valkey/commands/function_commands.rb', line 242

def function(subcommand, *args, **options)
  subcommand = subcommand.to_s.downcase

  if args.empty? && options.empty?
    send("function_#{subcommand}")
  elsif options.empty?
    send("function_#{subcommand}", *args)
  else
    send("function_#{subcommand}", *args, **options)
  end
end

#function_delete(library_name) ⇒ String

Delete a library and all its functions.

Examples:

Delete a library

valkey.function_delete("mylib")
  # => "OK"

Parameters:

  • library_name (String) —

    the library name to delete

Returns:

  • (String) —

    “OK”

See Also:



20
21
22
 
# File 'lib/valkey/commands/function_commands.rb', line 20

def function_delete(library_name)
  send_command(RequestType::FUNCTION_DELETE, [library_name])
end

#function_dump ⇒ String

Return the serialized payload of loaded libraries.

Examples:

Dump all libraries

valkey.function_dump
  # => <binary string>

Returns:

  • (String) —

    the serialized payload

See Also:



33
34
35
 
# File 'lib/valkey/commands/function_commands.rb', line 33

def function_dump
  send_command(RequestType::FUNCTION_DUMP)
end

#function_flush(async: false, sync: false) ⇒ String

Delete all libraries.

Examples:

Flush all libraries

valkey.function_flush
  # => "OK"

Flush all libraries asynchronously

valkey.function_flush(async: true)
  # => "OK"

Flush all libraries synchronously

valkey.function_flush(sync: true)
  # => "OK"

Parameters:

  • async (Boolean) (defaults to: false) —

    flush asynchronously

  • sync (Boolean) (defaults to: false) —

    flush synchronously

Returns:

  • (String) —

    “OK”

See Also:



54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/valkey/commands/function_commands.rb', line 54

def function_flush(async: false, sync: false)
  args = []

  if async
    args << "ASYNC"
  elsif sync
    args << "SYNC"
  end

  send_command(RequestType::FUNCTION_FLUSH, args)
end

#function_kill ⇒ String

Kill a function that is currently executing.

Examples:

Kill a running function

valkey.function_kill
  # => "OK"

Returns:

  • (String) —

    “OK”

See Also:



75
76
77
 
# File 'lib/valkey/commands/function_commands.rb', line 75

def function_kill
  send_command(RequestType::FUNCTION_KILL)
end

#function_list(library_name: nil, with_code: false) ⇒ Array<Hash>

Return information about the functions and libraries.

Examples:

List all libraries

valkey.function_list
  # => [{"library_name" => "mylib", "engine" => "LUA", ...}]

List libraries matching a pattern

valkey.function_list(library_name: "mylib*")
  # => [{"library_name" => "mylib", ...}]

List libraries with code

valkey.function_list(with_code: true)
  # => [{"library_name" => "mylib", "library_code" => "...", ...}]

Parameters:

  • library_name (String) (defaults to: nil) —

    filter by library name pattern

  • with_code (Boolean) (defaults to: false) —

    include the library code in the response

Returns:

  • (Array<Hash>) —

    array of library information

See Also:



96
97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/valkey/commands/function_commands.rb', line 96

def function_list(library_name: nil, with_code: false)
  args = []

  if library_name
    args << "LIBRARYNAME"
    args << library_name
  end

  args << "WITHCODE" if with_code

  send_command(RequestType::FUNCTION_LIST, args)
end

#function_load(function_code, replace: false) ⇒ String

Load a library to Valkey.

Examples:

Load a library

code = "#!lua name=mylib\nvalkey.register_function('myfunc', function(keys, args) return args[1] end)"
valkey.function_load(code)
  # => "mylib"

Load a library, replacing if exists

valkey.function_load(code, replace: true)
  # => "mylib"

Parameters:

  • function_code (String) —

    the source code

  • replace (Boolean) (defaults to: false) —

    replace the library if it exists

Returns:

  • (String) —

    the library name that was loaded

See Also:



124
125
126
127
128
129
130
 
# File 'lib/valkey/commands/function_commands.rb', line 124

def function_load(function_code, replace: false)
  args = []
  args << "REPLACE" if replace
  args << function_code

  send_command(RequestType::FUNCTION_LOAD, args)
end

#function_restore(serialized_value, policy: nil) ⇒ String

Restore libraries from a payload.

Examples:

Restore libraries

payload = valkey.function_dump
valkey.function_restore(payload)
  # => "OK"

Restore libraries with FLUSH policy

valkey.function_restore(payload, policy: "FLUSH")
  # => "OK"

Restore libraries with APPEND policy

valkey.function_restore(payload, policy: "APPEND")
  # => "OK"

Restore libraries with REPLACE policy

valkey.function_restore(payload, policy: "REPLACE")
  # => "OK"

Parameters:

  • serialized_value (String) —

    the serialized payload from FUNCTION DUMP

  • policy (String) (defaults to: nil) —

    the restore policy: “FLUSH”, “APPEND”, or “REPLACE”

Returns:

  • (String) —

    “OK”

See Also:



153
154
155
156
157
158
159
 
# File 'lib/valkey/commands/function_commands.rb', line 153

def function_restore(serialized_value, policy: nil)
  args = [serialized_value]

  args << policy.to_s.upcase if policy

  send_command(RequestType::FUNCTION_RESTORE, args)
end

#function_stats ⇒ Hash

Return information about the function that’s currently running.

Examples:

Get function stats

valkey.function_stats
  # => {"running_script" => {...}, "engines" => {...}}

Returns:

  • (Hash) —

    function execution statistics

See Also:



170
171
172
 
# File 'lib/valkey/commands/function_commands.rb', line 170

def function_stats
  send_command(RequestType::FUNCTION_STATS)
end