文档中心

缓存数据库 Redis 版

扩展模块

ExString

缓存数据库 Redis 版支持带版本号的 String 类型的扩展模块 ExString，本文介绍 ExString 扩展模块支持的命令。

前提条件

实例的版本需同时满足如下要求才可使用 ExString 扩展模块：

数据库版本需为 Redis 7.0。

Proxy 小版本需大于等于 1.22.0。

Server 小版本需大于等于 7.17.3。

说明

您可以在实例信息页签下查看实例的数据库版本和小版本信息，具体操作步骤，请参见查看实例信息。

实例状态需为运行中。关于实例状态的更多说明，请参见实例状态。

功能特性

缓存数据库 Redis 版提供的 ExString 在原生 Redis String 数据结构的基础上，额外支持了如下特性：

支持携带版本（version）信息，且版本信息允许修改。

ExString 在 Redis String 加减功能的基础上支持了边界设置，可以将 INCRBY、INCRBYFLOAT 的结果限制在一定的范围内，超出范围则提示错误。

命令语法

命令列表

ExString 支持的命令如下表所示。

说明

针对下表中的命令语法，定义如下：

大写关键字：命令关键字，如 EXSET。

小写关键字：可自定义的参数。

[]：[] 内的为可选参数，不在 [] 内的为必选参数。

<可选项 1>|<可选项 2>|<可选项 N>：一组互斥的参数可选项，即仅支持从可选项中选择一个参数进行设置。

命令	语法	说明
EXSET	EXSET key value [EX\|PX\|EXAT\|PXAT time] [NX\|XX] [VER\|ABS\|GT version] [KEEPTTL]	创建一个值为 value 的新 key；或为已存在的 key 设置一个新的 value。
EXGET	EXGET key	查询指定 key 的 value 与 version 信息。
EXSETVER	EXSETVER key version	设置指定 key 的 version。
EXINCRBY	EXINCRBY key num [MIN minval] [MAX maxval] [EX\|PX\|EXAT\|PXAT time] [NX\|XX] [VER\|ABS version][KEEPTTL]	对指定 key 的 value 进行增、减操作，num 的取值类型为 LONG。
EXINCRBYFLOAT	[EXINCRBYFLOAT key num [MIN minval] [MAX maxval] [EX\|PX\|EXAT\|PXAT time] [NX\|XX] [VER\|ABS version] [KEEPTTL]	对指定 key 的 value 进行增、减操作，num 的取值数据类型为 DOUBLE。
EXCAS	EXCAS key newvalue version	当传入的 version 与指定 key 的 version 一致时，则使用传入的 newvalue 覆盖原来的 value；若 version 不一致，则返回 key 当前的 value 和 version 信息。
EXCAD	EXCAD key version	当传入的 version 与指定 key 的 version 一致时，则删除 key。

注意事项

如需使用 ExString 功能，请提交工单联系技术支持申请使用。

申请完成后，拥有 Administrator 角色的账号默认具备 ExString 相关命令的所有权限。您也可以根据业务需要创建一个允许使用所有 ExString 类命令的新角色（即该角色的 ACL 规则需设置为 +@exstring），创建角色后，您需要通过拥有该角色的账号登录 Redis 后即可使用 ExString 相关命令。创建角色的具体操作步骤，请参见创建角色。

缓存数据库 Redis 版支持对 ExString 数据类型进行大、热 Key 分析，能够帮助及时发现并分析数据库中的热 Key 和大 Key 详情，为您优化热 Key 和大 Key 提供数据参考。具体操作步骤，请参见大 Key 分析和热 Key 分析。

成功申请使用 ExString 功能后，实例将不再支持任何数据恢复功能，包括：

按备份集恢复

按时间点恢复

恢复已删除实例

缓存数据库 Redis 版未提供删除 ExString 的命令，但您可以使用如下原生 Redis 命令实现删除 ExString 的目的。

命令	语法	说明
EXPIRE	EXPIRE key seconds [NX \| XX \| GT \| LT]	设置 ExString 的超时时间，超过该时间的 ExString 会被自动删除。
UNLINK	UNLINK key [key ...]	异步删除一个或多个 ExString。当通过 UNLINK 命令删除 ExString 时，这些 ExString 会被标记为待删除状态，而真正的删除操作会放在后台线程中进行，不会阻塞 Redis 的当前进程。
DEL	DEL key [key ...]	同步删除一个或多个 ExString。当通过 DEL 命令删除 ExString 时，删除操作会立即阻塞 Redis 当前线程，直到这些 ExString 对应的内存空间被完全回收释放。如果待删除的 ExString 数据量过大，可能会影响 Redis 整体性能。

EXSET

类别	说明
命令语法	EXSET key value [EX\|PX\|EXAT\|PXAT time] [NX\|XX] [VER\|ABS\|GT version] [KEEPTTL]
时间复杂度	O(1)。
命令描述	创建一个值为 value 的新 key；或为已存在的 key 设置一个新的 value。
选项	key：key 名称，用于指定作为命令调用对象的 ExString。 value：为 key 所设的 value。 EX time：指定 key 的相对过期时间，单位：秒，0 表示立即过期，不设置该参数表示 key 没有过期时间。 EXAT time：指定 key 的绝对过期时间，格式为 Unix 时间戳，单位：秒，0 表示立即过期，不设置该参数表示 key 没有过期时间。 PX time：指定 key 的相对过期时间，单位：毫秒，0 表示立即过期，不设置该参数表示 key 没有过期时间。 PXAT time：指定 key 的绝对过期时间，格式为 Unix 时间戳，单位：毫秒，0 表示立即过期，不设置该参数表示 key 没有过期时间。 NX：仅当 key 不存在时写入数据。 XX：仅当 key 存在时写入数据。 VER version：版本号。取值范围为 0 ~ Integer 数据类型允许的最大值。场景不同，版本号生效情况不同，其中：若 key 存在：且传入的版本号和 key 当前的版本号相等，那么直接写入 value，且版本号会在原来的版本号基础上加 1。但传入的版本号和 key 当前的版本号不相等，那么拒绝写入 value 并返回异常信息。若 key 不存在，那么忽略传入的版本号直接写入 value，写入成功后版本号变为 1。 ABS version：绝对版本号。取值范围为 0 ~ Integer 数据类型允许的最大值。设置后会直接写入 value，并将 key 的版本号修改为该选项所设的版本号。 GT version：比较版本号。取值范围为 0 ~ Integer 数据类型允许的最大值。设置后，只要指定 key 的版本号大于指定的 GT 版本号就会写入 value，且版本号会在原来的版本号基础上加 1。 KEEPTTL：延用该 key 已设置的过期时间（Time to live，TTL 信息）。说明 KEEPTTL 不能与 EX time、PX time、EXAT time、PXAT time 参数同时设置。若未设置 KEEPTTL 参数，也未设置 EX time、EXAT time、PX time、PXAT time 等设置过期时间的参数，则该 key 已设置的过期时间将被删除，即该 key 不会过期。
返回值	OK：执行成功。 nil：指定了 XX 参数但 key 不存在，或指定了 NX 参数但 key 已经存在。其他情况返回相应的异常信息（如 invalid arguments、update version is stale 等）。
示例	命令示例一创建一个 key 名称为 test_exstring ，值为 test_value1 的 ExString，并将该 ExString 的相对过期时间设置为 10 秒，绝对版本号为 100，指定仅当 key 不存在时写入。 EXSET test_exstring test_value1 EX 10 NX ABS 100 返回示例。 OK 命令示例二为已存在的 ExString test_exstring 赋一个新值 test_value2，并将该 ExString 的绝对过期时间设置为 100 毫秒，版本号为 100，指定仅当 key 存在时写入。 EXSET test_exstring test_value2 PXAT 1739455218750 XX VER 100 返回示例。 OK

EXGET

类别	说明
命令语法	EXGET key
时间复杂度	O(1)。
命令描述	查询指定 key 的 value 与 version 信息。
选项	key：key 名称，用于指定作为命令调用对象的 ExString。
返回值	执行成功时，会返回指定 key 的 value 与 version 信息。其他情况返回相应的异常信息（如 nil、wrong number of arguments for command 等）。
示例	命令示例。 EXGET test_exstring 返回示例。 1) test_value1 2) 100

EXSETVER

类别	说明
命令语法	EXSETVER key version
时间复杂度	O(1)。
命令描述	设置指定 key 的 version。
选项	key：key 名称，用于指定作为命令调用对象的 ExString。 version：需要设置的版本号，取值范围为 0 ~ Integer 数据类型允许的最大值。
返回值	1：执行成功。 0：指定的 key 不存在。其他情况返回相应的异常信息（如 syntax error 等）。
示例	命令示例。 EXSETVER test_exstring 66 返回示例。 1

EXINCRBY

类别	说明
命令语法	EXINCRBY key num [MIN minval] [MAX maxval] [EX\|PX\|EXAT\|PXAT time] [NX\|XX] [VER\|ABS version][KEEPTTL]
时间复杂度	O(1)。
命令描述	对指定 key 的 value 进行增、减操作，num 的取值类型为 LONG。
选项	key：key 名称，用于指定作为命令调用对象的 ExString。 num：需要进行增、减的数值，取值必须为整数，其中正整数为需要增加的数值，负整数为需要减少的数值。 MIN minval：设置指定 key 的 value 最小值。 MAX maxval：设置指定 key 的 value 最大值。 EX time：指定 key 的相对过期时间，单位：秒，0 表示立即过期，不设置该参数表示 key 没有过期时间。 EXAT time：指定 key 的绝对过期时间，格式为 Unix 时间戳，单位：秒，0 表示立即过期，不设置该参数表示 key 没有过期时间。 PX time：指定 key 的相对过期时间，单位：毫秒，0 表示立即过期，不设置该参数表示 key 没有过期时间。 PXAT time：指定 key 的绝对过期时间，格式为 Unix 时间戳，单位：毫秒，0 表示立即过期，不设置该参数表示 key 没有过期时间。 NX：仅当 key 不存在时写入数据。 XX：仅当 key 存在时写入数据。 VER version：版本号。取值范围为 0 ~ Integer 数据类型允许的最大值。场景不同，版本号生效情况不同，其中：若 key 存在：且传入的版本号和 key 当前的版本号相等，那么直接进行增减操作，且版本号会在原来的版本号基础上加 1。但传入的版本号和 key 当前的版本号不相等，那么拒绝进行增加操作并返回异常信息。 ABS version：绝对版本号。取值范围为 0 ~ Integer 数据类型允许的最大值。设置后会直接进行增减操作，并将 key 的版本号修改为该选项所设的版本号。 KEEPTTL：延用该 key 已设置的过期时间（Time to live，TTL 信息）。说明 KEEPTTL 不能与 EX time、PX time、EXAT time、PXAT time 参数同时设置。若未设置 KEEPTTL 参数，也未设置 EX time、EXAT time、PX time、PXAT time 等设置过期时间的参数，则该 key 已设置的过期时间将被删除，即该 key 不会过期。
返回值	执行成功时，会返回进行增减操作后获得的 value 值。当设置了 MAX maxval 或 MIN minval，且进行自增或自减操作后获得的 value 超过了该范围时，会返回 increment or decrement would overflow。其他情况返回相应的异常信息（如 update version is stale 等）。
示例	假设已使用 EXSET test_exstring1 25 ABS 100 命令创建了一个 ExString。您可以通过如下命令，在原值基础上再加上 15. EXINCRBY test_exstring1 15 MIN 35 VER 100 返回示例。 40

EXINCRBYFLOAT

类别	说明
命令语法	[EXINCRBYFLOAT key num [MIN minval] [MAX maxval] [EX\|PX\|EXAT\|PXAT time] [NX\|XX] [VER\|ABS version] [KEEPTTL]
时间复杂度	O(1)。
命令描述	对指定 key 的 value 进行增、减操作，num 的取值数据类型为 DOUBLE。
选项	key：key 名称，用于指定作为命令调用对象的 ExString。 num：需要进行增、减的数值，取值必须为浮点数，其中正浮点数为需要增加的数值，负浮点数为需要减少的数值。 MIN minval：设置指定 key 的 value 最小值。 MAX maxval：设置指定 key 的 value 最大值。 EX time：指定 key 的相对过期时间，单位：秒，0 表示立即过期，不设置该参数表示 key 没有过期时间。 EXAT time：指定 key 的绝对过期时间，格式为 Unix 时间戳，单位：秒，0 表示立即过期，不设置该参数表示 key 没有过期时间。 PX time：指定 key 的相对过期时间，单位：毫秒，0 表示立即过期，不设置该参数表示 key 没有过期时间。 PXAT time：指定 key 的绝对过期时间，格式为 Unix 时间戳，单位：毫秒，0 表示立即过期，不设置该参数表示 key 没有过期时间。 NX：仅当 key 不存在时写入数据。 XX：仅当 key 存在时写入数据。 VER version：版本号。取值范围为 0 ~ Integer 数据类型允许的最大值。场景不同，版本号生效情况不同，其中：若 key 存在：且传入的版本号和 key 当前的版本号相等，那么直接进行增减操作，且版本号会在原来的版本号基础上加 1。但传入的版本号和 key 当前的版本号不相等，那么拒绝进行增加操作并返回异常信息。 ABS version：绝对版本号。取值范围为 0 ~ Integer 数据类型允许的最大值。设置后会直接进行增减操作，并将 key 的版本号修改为该选项所设的版本号。 KEEPTTL：延用该 key 已设置的过期时间（Time to live，TTL 信息）。说明 KEEPTTL 不能与 EX time、PX time、EXAT time、PXAT time 参数同时设置。若未设置 KEEPTTL 参数，也未设置 EX time、EXAT time、PX time、PXAT time 等设置过期时间的参数，则该 key 已设置的过期时间将被删除，即该 key 不会过期。
返回值	执行成功时，会返回进行增减操作后获得的 value 值。当设置了 MAX maxval 或 MIN minval，且进行自增或自减操作后获得的 value 超过了该范围时，会返回 increment or decrement would overflow。其他情况返回相应的异常信息（如 update version is stale 等）。
示例	假设已使用 EXSET test_exstring1 25 ABS 100 命令创建了一个 ExString。您可以通过如下命令，在原值的基础上再减去 3.1415926. EXINCRBYFLOAT test_exstring1 -3.1415926 MAX 100 VER 100 返回示例。 21.8584074

EXCAS

类别	说明
命令语法	EXCAS key newvalue version
时间复杂度	O(1)。
命令描述	当传入的 version 与指定 key 的 version 一致时，则使用传入的 newvalue 覆盖原来的 value；若 version 不一致，则返回 key 当前的 value 和 version 信息。
选项	key：key 名称，用于指定作为命令调用对象的 ExString。 newvalue：若传入的 version 与指定 key 的 version 一致时，则使用传入的 newvalue 覆盖原来的 value。 version：用于与指定 key 当前 version 相比较的 version 值，取值范围为 0 ~ Integer 数据类型允许的最大值。
返回值	OK：命令执行成功，且同时会返回一行空字符串，以及 key 最新的 version 信息。 CAS_FAILED：命令执行失败，且同时会返回 key 当前的 value 和 version 版本。 -1：指定 key 不存在。其他情况返回相应的异常信息（如 syntax error、version should be integer 等）。
示例	假设已存在一个 ExString test_exstring1 且需要将该 ExString 的 value 改为 66，但不确定其当前的 value 和 version。您可以在如下命令中输入一个任意 version（例如 35），并尝试将原值修改为 66。 EXCAS test_exstring1 66 35 返回示例。 1) CAS_FAILED 2) 30 3) 100 从上述返回结果可知 test_exstring2 当前的 value 为 30， version 为 100，那么您可以通过如下命令将原值修改为 66。 EXCAS test_exstring1 66 100 返回示例。 1) OK 2) 3) 101

EXCAD

类别	说明
命令语法	EXCAD key version
时间复杂度	O(1)。
命令描述	当传入的 version 与指定 key 的 version 一致时，则删除 key。
选项	key：key 名称，用于指定作为命令调用对象的 ExString。 version：用于与指定 key 当前 version 相比较的 version 值，取值范围为 0 ~ Integer 数据类型允许的最大值。
返回值	1：执行成功。 0：执行失败。 -1：指定 key 不存在。其他情况返回相应的异常信息（如 syntax error、version should be integer 等）。
示例	假设已存在一个 version 为 100 的 ExString test_exstring1：当您使用如下命令时，删除 test_exstring1 会失败。 EXCAD test_exstring1 101 返回示例。 0 当您使用如下命令时，可成功删除 test_exstring1。 EXCAD test_exstring1 101 返回示例。 1

最近更新时间：2026.01.14 14:08:12

这个页面对您有帮助吗？

有用

无用