Redis.Function (Redis v0.8.0)

Copy Markdown View Source

High-level interface for Redis Functions (Redis 7+).

Redis Functions are persistent, named server-side routines that replace ad-hoc Lua scripting for production workloads. Libraries are loaded once and survive server restarts; individual functions within a library are invoked by name.

Usage

# Load a library
code = """
#!lua name=mylib
redis.register_function('myfunc', function(keys, args)
  return redis.call('GET', keys[1])
end)
"""
:ok = Redis.Function.load(conn, code)

# Call the function
{:ok, result} = Redis.Function.call(conn, "myfunc", keys: ["mykey"])

# Read-only variant (safe on replicas)
{:ok, result} = Redis.Function.call_ro(conn, "myfunc", keys: ["mykey"])

# List loaded libraries
{:ok, libs} = Redis.Function.list(conn)

# Clean up
:ok = Redis.Function.delete(conn, "mylib")

See also

Redis.Script for ad-hoc Lua scripting with SHA1-based caching.

Summary

Functions

call(conn, function_name, opts \\ [])

Calls a function by name via FCALL.

call_ro(conn, function_name, opts \\ [])

Calls a function by name via FCALL_RO (read-only variant).

delete(conn, library_name)

Deletes a function library by name.

dump(conn)

Returns a serialized payload of all loaded function libraries.

flush(conn, opts \\ [])

Deletes all function libraries.

list(conn, opts \\ [])

Lists loaded function libraries.

load(conn, code, opts \\ [])

Loads a function library into Redis.

restore(conn, data, opts \\ [])

Restores function libraries from a serialized payload produced by dump/1.

stats(conn)

Returns information about function execution statistics.

Functions

call(conn, function_name, opts \\ [])

@spec call(GenServer.server(), String.t(), keyword()) ::
  {:ok, term()} | {:error, term()}

Calls a function by name via FCALL.

Options

  • :keys - list of Redis keys (default: [])
  • :args - list of additional arguments (default: [])

call_ro(conn, function_name, opts \\ [])

@spec call_ro(GenServer.server(), String.t(), keyword()) ::
  {:ok, term()} | {:error, term()}

Calls a function by name via FCALL_RO (read-only variant).

Safe for use on replicas. Accepts the same options as call/3.

delete(conn, library_name)

@spec delete(GenServer.server(), String.t()) :: :ok | {:error, term()}

Deletes a function library by name.

Returns :ok on success or {:error, reason} on failure.

dump(conn)

@spec dump(GenServer.server()) :: {:ok, binary()} | {:error, term()}

Returns a serialized payload of all loaded function libraries.

The result can be restored on another server with restore/3.

flush(conn, opts \\ [])

@spec flush(
  GenServer.server(),
  keyword()
) :: :ok | {:error, term()}

Deletes all function libraries.

Options

  • :mode - :async or :sync (default: server decides)

list(conn, opts \\ [])

@spec list(
  GenServer.server(),
  keyword()
) :: {:ok, term()} | {:error, term()}

Lists loaded function libraries.

Options

  • :libraryname - filter by library name pattern
  • :withcode - include library source code in the response (default: false)

load(conn, code, opts \\ [])

@spec load(GenServer.server(), String.t(), keyword()) :: :ok | {:error, term()}

Loads a function library into Redis.

The code must include a shebang header declaring the engine and library name, e.g. #!lua name=mylib.

Options

  • :replace - overwrite an existing library with the same name (default: false)

Returns :ok on success or {:error, reason} on failure.

restore(conn, data, opts \\ [])

@spec restore(GenServer.server(), binary(), keyword()) :: :ok | {:error, term()}

Restores function libraries from a serialized payload produced by dump/1.

Options

  • :flush - delete all existing libraries before restoring
  • :append - append to existing libraries (error on name conflict)
  • :replace - replace existing libraries with same name

stats(conn)

@spec stats(GenServer.server()) :: {:ok, term()} | {:error, term()}

Returns information about function execution statistics.