Redis 函数

使用 Redis 7 及更高版本编写脚本

Redis Functions 是用于管理要在服务器上执行的代码的 API。此功能在 Redis 7 中可用，取代了 Redis 早期版本中对 EVAL 的使用。

序言（或者，Eval Scripts 有什么问题？

以前的 Redis 版本使脚本只能通过EVAL命令，它允许发送 Lua 脚本以供服务器执行。 Eval Scripts 的核心用例是在 Redis 中高效、原子地执行部分应用程序逻辑。此类脚本可以跨多个键执行条件更新，可能组合几种不同的数据类型。

用EVAL要求应用程序每次都发送整个脚本执行。由于这会导致网络和脚本编译开销，因此 Redis 以EVALSHA命令。通过首次调用SCRIPT LOAD要获取脚本的 SHA1，应用程序可以在之后仅使用其摘要重复调用它。

根据设计，Redis 仅缓存加载的脚本。这意味着脚本缓存可能随时丢失，例如在调用SCRIPT FLUSH、重新启动服务器后或故障转移到副本时。如果缺少任何脚本，应用程序负责在运行时重新加载脚本。基本假设是脚本是应用程序的一部分，而不是由 Redis 服务器维护。

这种方法适合许多轻量级脚本用例，但一旦应用程序变得复杂并且更加依赖脚本，就会带来一些困难，即：

所有客户端应用程序实例都必须维护所有脚本的副本。这意味着具有某种机制，将脚本更新应用于应用程序的所有实例。
在事务上下文中调用缓存的脚本会增加事务因缺少脚本而失败的可能性。失败的可能性更大，使用缓存的脚本作为工作流的构建块的吸引力会降低。
SHA1 摘要毫无意义，这使得调试系统变得非常困难（例如，在MONITORsession）的 Session）。
当天真地使用时，EVAL提升了一种反模式，在该模式中，客户端应用程序逐字呈现脚本，而不是负责任地使用KEYS和ARGVLua API 接口.
因为它们是临时的，所以一个脚本不能调用另一个脚本。这使得在脚本之间共享和重用代码几乎是不可能的，除非客户端预处理（参见第一点）。

为了满足这些需求，同时避免对已建立且广受欢迎的临时脚本进行中断性更改，Redis v7.0 引入了 Redis 函数。

什么是 Redis 函数？

Redis 函数是从临时脚本演变而来的步骤。

函数提供与脚本相同的核心功能，但却是数据库的一流软件工件。 Redis 将函数作为数据库不可或缺的一部分进行管理，并通过数据持久性和复制确保其可用性。由于函数是数据库的一部分，因此在使用前声明，因此应用程序不需要在运行时加载它们，也不需要冒着中止事务的风险。使用函数的应用程序仅依赖于其 API，而不依赖于数据库中的嵌入式脚本逻辑。

临时脚本被视为应用程序域的一部分，而 Functions 使用用户提供的逻辑扩展数据库服务器本身。它们可用于公开由核心 Redis 命令组成的更丰富的 API，类似于模块，开发一次，在启动时加载，并被各种应用程序/客户端重复使用。每个函数都有一个唯一的用户定义名称，这使得调用和跟踪其执行变得更加容易。

Redis Functions 的设计还试图区分用于编写函数的编程语言和服务器对它们的管理。 Lua 是 Redis 目前唯一支持作为嵌入式执行引擎的语言解释器，旨在简单易学。然而，选择 Lua 作为一种语言仍然给许多 Redis 用户带来了挑战。

Redis Functions 功能对实现的语言不做任何假设。作为函数定义一部分的执行引擎负责运行它。理论上，引擎可以执行任何语言的函数，只要它遵守多个规则（例如终止正在执行的函数的能力）。

目前，如上所述，Redis 附带了一个嵌入式 Lua 5.1 引擎。未来有计划支持其他引擎。 Redis 函数可以将 Lua 的所有可用功能用于临时脚本、唯一的例外是 Redis Lua 脚本调试器。

Functions 还通过启用代码共享来简化开发。每个函数都属于一个库，任何给定的库都可以由多个函数组成。库的内容是不可变的，并且不允许选择性更新其函数。相反，库作为一个整体进行更新，所有功能都在一个作中一起更新。这允许从同一库中的其他函数调用函数，或者通过使用库内部方法中的通用代码在函数之间共享代码，该代码也可以采用语言本机参数。

如上所述，Functions 旨在更好地支持通过逻辑架构维护数据实体视图一致视图的使用案例。因此，函数与数据本身一起存储。函数也会持久化到 AOF 文件中，并从主服务器复制到副本服务器，因此它们与数据本身一样持久。当 Redis 用作临时缓存时，需要其他机制（如下所述）来提高函数的持久性。

与 Redis 中的所有其他作一样，函数的执行是原子的。函数的执行会在其整个时间内阻止所有服务器活动，这与事务的语义类似。这些语义意味着脚本的所有效果要么尚未发生，要么已经发生。已执行函数的阻塞语义始终适用于所有连接的客户端。由于运行函数会阻止 Redis 服务器，因此函数旨在快速完成执行，因此应避免使用长时间运行的函数。

加载库和函数

让我们通过一些有形的示例和 Lua 片段来探索 Redis 函数。

此时，如果您不熟悉 Lua，特别是 Redis 中的 Lua，则查看 Eval 脚本简介和 Lua API 页面中的一些示例可能会有所帮助，以便更好地掌握该语言。

每个 Redis 函数都属于加载到 Redis 的单个库。将库加载到数据库是通过FUNCTION LOAD命令。该命令将库有效负载作为输入库有效负载必须以 Shebang 语句开头，该语句提供有关库的元数据（如要使用的引擎和库名称）。 Shebang 格式为：

#!<engine name> name=<library name>

让我们尝试加载一个空库：

redis> FUNCTION LOAD "#!lua name=mylib\n"
(error) ERR No functions registered

该错误是意料之中的，因为加载的库中没有函数。每个库都需要包含至少一个已注册的函数才能成功加载。已注册的函数被命名并充当库的入口点。当目标执行引擎处理FUNCTION LOAD命令，它会注册库的函数。

Lua 引擎在加载时编译和评估库源代码，并希望通过调用redis.register_function()应用程序接口。

以下代码段演示了一个简单的库，该库注册了一个名为 knockknock 的函数，并返回一个字符串 reply：

#!lua name=mylib
redis.register_function(
  'knockknock',
  function() return 'Who\'s there?' end
)

In the example above, we provide two arguments about the function to Lua's redis.register_function() API: its registered name and a callback.


We can load our library and use FCALL to call the registered function:
redis> FUNCTION LOAD "#!lua name=mylib\nredis.register_function('knockknock', function() return 'Who\\'s there?' end)"
mylib
redis> FCALL knockknock 0
"Who's there?"
Notice that the FUNCTION LOAD command returns the name of the loaded library, this name can later be used FUNCTION LIST and FUNCTION DELETE.
We've provided FCALL with two arguments: the function's registered name and the numeric value 0. This numeric value indicates the number of key names that follow it (the same way EVAL and EVALSHA work).
We'll explain immediately how key names and additional arguments are available to the function. As this simple example doesn't involve keys, we simply use 0 for now.
Input keys and regular arguments
Before we move to the following example, it is vital to understand the distinction Redis makes between arguments that are names of keys and those that aren't.
While key names in Redis are just strings, unlike any other string values, these represent keys in the database.
The name of a key is a fundamental concept in Redis and is the basis for operating the Redis Cluster.
Important:
To ensure the correct execution of Redis Functions, both in standalone and clustered deployments, all names of keys that a function accesses must be explicitly provided as input key arguments.
Any input to the function that isn't the name of a key is a regular input argument.
Now, let's pretend that our application stores some of its data in Redis Hashes.
We want an HSET-like way to set and update fields in said Hashes and store the last modification time in a new field named _last_modified_.
We can implement a function to do all that.
Our function will call TIME to get the server's clock reading and update the target Hash with the new fields' values and the modification's timestamp.
The function we'll implement accepts the following input arguments: the Hash's key name and the field-value pairs to update.
The Lua API for Redis Functions makes these inputs accessible as the first and second arguments to the function's callback.
The callback's first argument is a Lua table populated with all key names inputs to the function.
Similarly, the callback's second argument consists of all regular arguments.
The following is a possible implementation for our function and its library registration:
#!lua name=mylib

local function my_hset(keys, args)
  local hash = keys[1]
  local time = redis.call('TIME')[1]
  return redis.call('HSET', hash, '_last_modified_', time, unpack(args))
end

redis.register_function('my_hset', my_hset)
If we create a new file named mylib.lua that consists of the library's definition, we can load it like so (without stripping the source code of helpful whitespaces):

$ cat mylib.lua | redis-cli -x FUNCTION LOAD REPLACE
We've added the REPLACE modifier to the call to FUNCTION LOAD to tell Redis that we want to overwrite the existing library definition.
Otherwise, we would have gotten an error from Redis complaining that the library already exists.

Now that the library's updated code is loaded to Redis, we can proceed and call our function:
redis> FCALL my_hset 1 myhash myfield "some value" another_field "another value"
(integer) 3
redis> HGETALL myhash
1) "_last_modified_"
2) "1640772721"
3) "myfield"
4) "some value"
5) "another_field"
6) "another value"
In this case, we had invoked FCALL with 1 as the number of key name arguments.
That means that the function's first input argument is a name of a key (and is therefore included in the callback's keys table).
After that first argument, all following input arguments are considered regular arguments and constitute the args table passed to the callback as its second argument.
Expanding the library
We can add more functions to our library to benefit our application.
The additional metadata field we've added to the Hash shouldn't be included in responses when accessing the Hash's data.
On the other hand, we do want to provide the means to obtain the modification timestamp for a given Hash key.
We'll add two new functions to our library to accomplish these objectives:

The my_hgetall Redis Function will return all fields and their respective values from a given Hash key name, excluding the metadata (i.e., the _last_modified_ field).
The my_hlastmodified Redis Function will return the modification timestamp for a given Hash key name.

The library's source code could look something like the following:
#!lua name=mylib

local function my_hset(keys, args)
  local hash = keys[1]
  local time = redis.call('TIME')[1]
  return redis.call('HSET', hash, '_last_modified_', time, unpack(args))
end

local function my_hgetall(keys, args)
  redis.setresp(3)
  local hash = keys[1]
  local res = redis.call('HGETALL', hash)
  res['map']['_last_modified_'] = nil
  return res
end

local function my_hlastmodified(keys, args)
  local hash = keys[1]
  return redis.call('HGET', hash, '_last_modified_')
end

redis.register_function('my_hset', my_hset)
redis.register_function('my_hgetall', my_hgetall)
redis.register_function('my_hlastmodified', my_hlastmodified)
While all of the above should be straightforward, note that the my_hgetall also calls redis.setresp(3).
That means that the function expects RESP3 replies after calling redis.call(), which, unlike the default RESP2 protocol, provides dictionary (associative arrays) replies.
Doing so allows the function to delete (or set to nil as is the case with Lua tables) specific fields from the reply, and in our case, the _last_modified_ field.

Assuming you've saved the library's implementation in the mylib.lua file, you can replace it with:
$ cat mylib.lua | redis-cli -x FUNCTION LOAD REPLACE
Once loaded, you can call the library's functions with FCALL:

redis> FCALL my_hgetall 1 myhash
1) "myfield"
2) "some value"
3) "another_field"
4) "another value"
redis> FCALL my_hlastmodified 1 myhash
"1640772721"
You can also get the library's details with the FUNCTION LIST command:
redis> FUNCTION LIST
1) 1) "library_name"
   2) "mylib"
   3) "engine"
   4) "LUA"
   5) "functions"
   6) 1) 1) "name"
         2) "my_hset"
         3) "description"
         4) (nil)
         5) "flags"
         6) (empty array)
      2) 1) "name"
         2) "my_hgetall"
         3) "description"
         4) (nil)
         5) "flags"
         6) (empty array)
      3) 1) "name"
         2) "my_hlastmodified"
         3) "description"
         4) (nil)
         5) "flags"
         6) (empty array)
You can see that it is easy to update our library with new capabilities.
Reusing code in the library
On top of bundling functions together into database-managed software artifacts, libraries also facilitate code sharing.
We can add to our library an error handling helper function called from other functions.
The helper function check_keys() verifies that the input keys table has a single key.
Upon success it returns nil, otherwise it returns an error reply.
The updated library's source code would be:
#!lua name=mylib

local function check_keys(keys)
  local error = nil
  local nkeys = table.getn(keys)
  if nkeys == 0 then
    error = 'Hash key name not provided'
  elseif nkeys > 1 then
    error = 'Only one key name is allowed'
  end

  if error ~= nil then
    redis.log(redis.LOG_WARNING, error);
    return redis.error_reply(error)
  end
  return nil
end

local function my_hset(keys, args)
  local error = check_keys(keys)
  if error ~= nil then
    return error
  end

  local hash = keys[1]
  local time = redis.call('TIME')[1]
  return redis.call('HSET', hash, '_last_modified_', time, unpack(args))
end

local function my_hgetall(keys, args)
  local error = check_keys(keys)
  if error ~= nil then
    return error
  end

  redis.setresp(3)
  local hash = keys[1]
  local res = redis.call('HGETALL', hash)
  res['map']['_last_modified_'] = nil
  return res
end

local function my_hlastmodified(keys, args)
  local error = check_keys(keys)
  if error ~= nil then
    return error
  end

  local hash = keys[1]
  return redis.call('HGET', keys[1], '_last_modified_')
end

redis.register_function('my_hset', my_hset)
redis.register_function('my_hgetall', my_hgetall)
redis.register_function('my_hlastmodified', my_hlastmodified)
After you've replaced the library in Redis with the above, you can immediately try out the new error handling mechanism:

127.0.0.1:6379> FCALL my_hset 0 myhash nope nope
(error) Hash key name not provided
127.0.0.1:6379> FCALL my_hgetall 2 myhash anotherone
(error) Only one key name is allowed
And your Redis log file should have lines in it that are similar to:
...
20075:M 1 Jan 2022 16:53:57.688 # Hash key name not provided
20075:M 1 Jan 2022 16:54:01.309 # Only one key name is allowed
Functions in cluster
As noted above, Redis automatically handles propagation of loaded functions to replicas.
In a Redis Cluster, it is also necessary to load functions to all cluster nodes. This is not handled automatically by Redis Cluster, and needs to be handled by the cluster administrator (like module loading, configuration setting, etc.).
As one of the goals of functions is to live separately from the client application, this should not be part of the Redis client library responsibilities. Instead, redis-cli --cluster-only-masters --cluster call host:port FUNCTION LOAD ... can be used to execute the load command on all master nodes.
Also, note that redis-cli --cluster add-node automatically takes care to propagate the loaded functions from one of the existing nodes to the new node.
Functions and ephemeral Redis instances
In some cases there may be a need to start a fresh Redis server with a set of functions pre-loaded. Common reasons for that could be:

Starting Redis in a new environment
Re-starting an ephemeral (cache-only) Redis, that uses functions

In such cases, we need to make sure that the pre-loaded functions are available before Redis accepts inbound user connections and commands.
To do that, it is possible to use redis-cli --functions-rdb to extract the functions from an existing server. This generates an RDB file that can be loaded by Redis at startup.
Function flags
Redis needs to have some information about how a function is going to behave when executed, in order to properly enforce resource usage policies and maintain data consistency.
For example, Redis needs to know that a certain function is read-only before permitting it to execute using FCALL_RO on a read-only replica.
By default, Redis assumes that all functions may perform arbitrary read or write operations. Function Flags make it possible to declare more specific function behavior at the time of registration. Let's see how this works.
In our previous example, we defined two functions that only read data. We can try executing them using FCALL_RO against a read-only replica.
redis > FCALL_RO my_hgetall 1 myhash
(error) ERR Can not execute a function with write flag using fcall_ro.
Redis returns this error because a function can, in theory, perform both read and write operations on the database.
As a safeguard and by default, Redis assumes that the function does both, so it blocks its execution.
The server will reply with this error in the following cases:

Executing a function with FCALL against a read-only replica.
Using FCALL_RO to execute a function.
A disk error was detected (Redis is unable to persist so it rejects writes).

In these cases, you can add the no-writes flag to the function's registration, disable the safeguard and allow them to run.
To register a function with flags use the named arguments variant of redis.register_function.
The updated registration code snippet from the library looks like this:
redis.register_function('my_hset', my_hset)
redis.register_function{
  function_name='my_hgetall',
  callback=my_hgetall,
  flags={ 'no-writes' }
}
redis.register_function{
  function_name='my_hlastmodified',
  callback=my_hlastmodified,
  flags={ 'no-writes' }
}
Once we've replaced the library, Redis allows running both my_hgetall and my_hlastmodified with FCALL_RO against a read-only replica:

redis> FCALL_RO my_hgetall 1 myhash
1) "myfield"
2) "some value"
3) "another_field"
4) "another value"
redis> FCALL_RO my_hlastmodified 1 myhash
"1640772721"
For the complete documentation flags, please refer to Script flags.

        

  
  
    
      RATE THIS PAGE
      
        
        
        ★
        
        
        ★
        
        
        ★
        
        
        ★
        
        
        ★
        
      
      
    
      Back to top ↑

Redis 函数

序言（或者，Eval Scripts 有什么问题？

什么是 Redis 函数？

加载库和函数

Input keys and regular arguments

Expanding the library

Reusing code in the library

Functions in cluster

Functions and ephemeral Redis instances

Function flags

On this page