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: [], route: nil) ⇒ 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

  • route (Valkey::Route, nil) (defaults to: nil) —

    cluster routing. When routed, may return a Hash of node => value.

Returns:

  • (Object) —

    the function result

See Also:



198
199
200
201
 
# File 'lib/valkey/commands/function_commands.rb', line 198

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

#fcall_ro(function, keys: [], args: [], route: nil) ⇒ 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

  • route (Valkey::Route, nil) (defaults to: nil) —

    cluster routing. When routed, may return a Hash of node => value.

Returns:

  • (Object) —

    the function result

See Also:



216
217
218
219
 
# File 'lib/valkey/commands/function_commands.rb', line 216

def fcall_ro(function, keys: [], args: [], route: nil)
  command_args = [function, keys.size] + keys + args
  send_command(RequestType::FCALL_READ_ONLY, command_args, route: route)
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



252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/valkey/commands/function_commands.rb', line 252

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, route: nil) ⇒ 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

  • route (Valkey::Route, nil) (defaults to: nil) —

    cluster routing.

Returns:

  • (String) —

    "OK"

See Also:



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

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

#function_dump(route: nil) ⇒ String

Return the serialized payload of loaded libraries.

Examples:

Dump all libraries

valkey.function_dump
  # => <binary string>

Parameters:

  • route (Valkey::Route, nil) (defaults to: nil) —

    cluster routing. When routed, may return a Hash of node => value.

Returns:

  • (String) —

    the serialized payload

See Also:



35
36
37
 
# File 'lib/valkey/commands/function_commands.rb', line 35

def function_dump(route: nil)
  send_command(RequestType::FUNCTION_DUMP, [], route: route)
end

#function_flush(async: false, sync: false, route: nil) ⇒ 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

  • route (Valkey::Route, nil) (defaults to: nil) —

    cluster routing.

Returns:

  • (String) —

    "OK"

See Also:



57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/valkey/commands/function_commands.rb', line 57

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

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

  send_command(RequestType::FUNCTION_FLUSH, args, route: route)
end

#function_kill(route: nil) ⇒ String

Kill a function that is currently executing.

Examples:

Kill a running function

valkey.function_kill
  # => "OK"

Parameters:

  • route (Valkey::Route, nil) (defaults to: nil) —

    cluster routing.

Returns:

  • (String) —

    "OK"

See Also:



79
80
81
 
# File 'lib/valkey/commands/function_commands.rb', line 79

def function_kill(route: nil)
  send_command(RequestType::FUNCTION_KILL, [], route: route)
end

#function_list(library_name: nil, with_code: false, route: nil) ⇒ 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

  • route (Valkey::Route, nil) (defaults to: nil) —

    cluster routing. When routed, may return a Hash of node => value.

Returns:

  • (Array<Hash>) —

    array of library information

See Also:



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

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

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

  args << "WITHCODE" if with_code

  send_command(RequestType::FUNCTION_LIST, args, route: route)
end

#function_load(function_code, replace: false, route: nil) ⇒ 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

  • route (Valkey::Route, nil) (defaults to: nil) —

    cluster routing.

Returns:

  • (String) —

    the library name that was loaded

See Also:



130
131
132
133
134
135
136
 
# File 'lib/valkey/commands/function_commands.rb', line 130

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

  send_command(RequestType::FUNCTION_LOAD, args, route: route)
end

#function_restore(serialized_value, policy: nil, route: 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"

  • route (Valkey::Route, nil) (defaults to: nil) —

    cluster routing.

Returns:

  • (String) —

    "OK"

See Also:



160
161
162
163
164
165
166
 
# File 'lib/valkey/commands/function_commands.rb', line 160

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

  args << policy.to_s.upcase if policy

  send_command(RequestType::FUNCTION_RESTORE, args, route: route)
end

#function_stats(route: nil) ⇒ Hash

Return information about the function that's currently running.

Examples:

Get function stats

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

Parameters:

  • route (Valkey::Route, nil) (defaults to: nil) —

    cluster routing. When routed, may return a Hash of node => value.

Returns:

  • (Hash) —

    function execution statistics

See Also:



178
179
180
 
# File 'lib/valkey/commands/function_commands.rb', line 178

def function_stats(route: nil)
  send_command(RequestType::FUNCTION_STATS, [], route: route)
end