本章节介绍TairString数据支持的命令。
TairString简介
TairString是一种带版本号的string类型数据结构。Redis的String仅由key和value组成，而TairString不仅包含key和value，还携带了版本（version），可用于乐观锁等场景。除此之外，TairString在Redis String加减功能的基础上支持了边界设置，可以将INCRBY、INCRBYFLOAT的结果限制在一定的范围内，超出范围则提示错误。
主要特性：
- value携带版本号。
- 使用INCRBY、INCRBYFLOAT递增数据时可设置变更范围。
警告 TairString与Redis原生String是两种不同的数据结构，相关命令不可混用。
使用前提
请注意，本章节介绍的命令只有在满足以下条件时才能生效。
- Redis实例为云Redis企业版性能增强型实例。
- 操作对象为性能增强型实例中的TairString数据。
说明 性能增强型实例中可同时设置Redis String（即Redis原生String）和TairString，本章节的命令无法对Redis String使用。
命令列表
| 命令 | 语法 | 简介 |
|---|---|---|
| EXSET | EXSET <key> <value> [EX time] [PX time] [EXAT time] [PXAT time] [NX | XX] [VER version | ABS version] | 将value保存到key中。 |
| EXGET | EXGET <key> | 返回TairString的value和version。 |
| EXSETVER | EXSETVER <key> <version> | 直接对一个key设置version。 |
| EXINCRBY | EXINCRBY <key> <num> [EX time] [PX time] [EXAT time] [EXAT time] [PXAT time] [NX | XX] [VER version | ABS version] [MIN minval] [MAX maxval] | 对Key做自增自减操作，num的范围为long。 |
| EXINCRBYFLOAT | EXINCRBYFLOAT <key> <num> [EX time] [PX time] [EXAT time] [EXAT time] [PXAT time] [NX | XX] [VER version | ABS version] [MIN minval] [MAX maxval] | 对Key做自增自减操作，num的范围为double。 |
| EXCAS | EXCAS <key> <newvalue> <version> | 指定version将value更新，当引擎中的version和指定的相同时才更新成功，不成功会返回旧的value和version。 |
| EXCAD | EXCAD <key> <version> | 当指定version和引擎中version相等时候删除Key，否则失败。 |
| DEL | DEL <key> [key …] | 使用原生Redis的DEL命令可以删除一条或多条TairString数据。 |
EXSET
- 语法
EXSET <key> <value> [EX time] [PX time] [EXAT time] [EXAT time] [PXAT time] [NX | XX] [VER version | ABS version]
- 时间复杂度
O(1)
- 命令描述
将value保存到key中。
- 参数及选项说明
参数/选项 说明 key TairString的key，用于指定作为命令调用对象的TairString。 value 需要为key设置的value。 EX 指定key的相对超时时间，单位为秒，为0表示立即过期。 EXAT 指定key的绝对超时时间，单位为秒，为0表示立即过期。 PX 指定key的相对超时时间，单位为毫秒，为0表示立即过期。 PXAT 指定key的绝对超时时间，单位为毫秒 ，为0表示立即过期。 NX 只在key不存在时写入。 XX 只在key存在时写入。 VER 版本号。 - 如果key存在，和当前版本号做比较：
- 如果相等，写入，且版本号加1。
- 如果不相等，返回异常。
- 如果key不存在或者key当前版本为0，忽略传入的版本号直接设置value，成功后版本号变为1。
ABS 绝对版本号。设置后，无论key当前的版本号是多少，完成写入并将key的版本号覆盖为该选项中设置的值。 - 如果key存在，和当前版本号做比较：
- 返回值
- 成功：OK。
- 其它情况返回异常。
- 使用示例
127.0.0.1:6379> EXSET foo bar XX (nil) 127.0.0.1:6379> EXSET foo bar NX OK 127.0.0.1:6379> EXSET foo bar NX (nil) 127.0.0.1:6379> EXGET foo 1) "bar" 2) (integer) 1 127.0.0.1:6379> EXSET foo bar1 VER 10 (error) ERR update version is stale 127.0.0.1:6379> EXSET foo bar1 VER 1 OK 127.0.0.1:6379> EXGET foo 1) "bar1" 2) (integer) 2 127.0.0.1:6379> EXSET foo bar2 ABS 100 OK 127.0.0.1:6379> EXGET foo 1) "bar2" 2) (integer) 100
EXGET
- 语法
EXGET <key>
- 时间复杂度
O(1)
- 命令描述
获取TairString的value和version。
- 参数及选项说明
key：TairString的key，用于指定作为命令调用对象的TairString。
- 返回值
- 成功：value+version。
- 其它情况返回异常。
- 使用示例
127.0.0.1:6379> EXSET foo bar ABS 100 OK 127.0.0.1:6379> EXGET foo 1) "bar" 2) (integer) 100 127.0.0.1:6379> DEL foo (integer) 1 127.0.0.1:6379> EXGET foo (nil)
EXSETVER
- 语法
EXSETVER <key> <version>
- 时间复杂度
O(1)
- 命令描述
直接对一个key设置version。
- 参数及选项说明
参数/选项 说明 key TairString的key，用于指定作为命令调用对象的TairString。 version 需要设置的版本号。 - 返回值
- 成功：1。
- key不存在：0。
- 其它情况返回异常。
- 使用示例
127.0.0.1:6379> EXSET foo bar OK 127.0.0.1:6379> EXGET foo 1) "bar" 2) (integer) 1 127.0.0.1:6379> EXSETVER foo 2 (integer) 1 127.0.0.1:6379> EXGET foo 1) "bar" 2) (integer) 2 127.0.0.1:6379> EXSETVER not-exists 0 (integer) 0
EXINCRBY
- 语法
EXINCRBY |EXINCRBY <key> <num> [EX time] [PX time] [EXAT time] [EXAT time] [PXAT time] [NX | XX] [VER version | ABS version] [MIN minval] [MAX maxval]
- 时间复杂度
O(1)
- 命令描述
对TairString的value做自增自减操作，num的范围为long。
- 参数及选项说明
参数/选项 说明 key TairString的key，用于指定作为命令调用对象的TairString。 num TairString自增的数值，必须为整数。 EX 指定key的相对超时时间，单位为秒，为0表示立即过期。 EXAT 指定key的绝对超时时间，单位为秒，为0表示立即过期。 PX 指定key的相对超时时间，单位为毫秒，为0表示立即过期。 PXAT 指定key的绝对超时时间，单位为毫秒 ，为0表示立即过期。 NX 只在key不存在时写入。 XX 只在key存在时写入。 VER 版本号。 - 如果key存在，和当前版本号做比较：
- 如果相等，进行自增，且版本号加1。
- 如果不相等，返回异常。
- 如果key不存在或者key当前版本为0，忽略传入的版本号并进行自增操作，成功后版本号变为1。
ABS 绝对版本号。设置后，无论key当前的版本号是多少，完成自增并将key的版本号覆盖为该选项中设置的值。 MIN TairString value的最小值。 MAX TairString value的最大值。 - 如果key存在，和当前版本号做比较：
- 返回值
- 成功：value的当前值。
- 其它情况返回异常。
- 使用示例
127.0.0.1:6379> EXINCRBY foo 100 (integer) 100 127.0.0.1:6379> EXINCRBY foo 100 MAX 150 (error) ERR increment or decrement would overflow 127.0.0.1:6379> FLUSHALL OK 127.0.0.1:6379> EXINCRBY foo 100 (integer) 100 127.0.0.1:6379> EXINCRBY foo 100 MAX 150 (error) ERR increment or decrement would overflow 127.0.0.1:6379> EXINCRBY foo 100 MAX 300 (integer) 200 127.0.0.1:6379> EXINCRBY foo 100 MIN 500 (error) ERR increment or decrement would overflow 127.0.0.1:6379> EXINCRBY foo 100 MIN 500 MAX 100 (error) ERR min or max is specified, but not valid 127.0.0.1:6379> EXINCRBY foo 100 MIN 50 (integer) 300
EXINCRBYFLOAT
- 语法
EXINCRBYFLOAT |EXINCRBYFLOAT <key> <num> [EX time] [PX time] [EXAT time] [EXAT time] [PXAT time] [NX | XX] [VER version | ABS version] [MIN minval] [MAX maxval]
- 时间复杂度
O(1)
- 命令描述
对TairString的value做自增自减操作，num的范围为double。
- 参数及选项说明
参数/选项 说明 key TairString的key，用于指定作为命令调用对象的TairString。 num TairString自增的数值，类型为浮点数。 EX 指定key的相对超时时间，单位为秒，为0表示立即过期。 EXAT 指定key的绝对超时时间，单位为秒，为0表示立即过期。 PX 指定key的相对超时时间，单位为毫秒，为0表示立即过期。 PXAT 指定key的绝对超时时间，单位为毫秒 ，为0表示立即过期。 NX 当数据不存在时写入。 XX 当数据存在时写入。 VER 版本号。 - 如果key存在，和当前版本号做比较：
- 如果相等，进行自增，且版本号加1。
- 如果不相等，返回异常。
- 如果key不存在或者key当前版本为0，忽略传入的版本号并进行自增操作，成功后版本号变为1。
ABS 绝对版本号。设置后，无论key当前的版本号是多少，完成自增并将key的版本号覆盖为该选项中设置的值。 MIN TairString value的最小值。 MAX TairString value的最大值。 - 如果key存在，和当前版本号做比较：
- 返回值
- 成功：value的当前值。
- 其它情况返回异常。
- 使用示例
127.0.0.1:6379> EXSET foo 100 OK 127.0.0.1:6379> EXINCRBYFLOAT foo 10.123 "110.123" 127.0.0.1:6379> EXINCRBYFLOAT foo 20 MAX 100 (error) ERR increment or decrement would overflow 127.0.0.1:6379> EXINCRBYFLOAT foo 20 MIN 100 "130.123" 127.0.0.1:6379> EXGET foo 1) "130.123" 2) (integer) 3
EXCAS
- 语法
EXCAS <key> <newvalue> <version>
- 时间复杂度
O(1)
- 命令描述
当指定key的版本值和命令中设置的version相等时，将key的value修改为一个新的值；不相等则不修改。
- 参数及选项说明
参数/选项 说明 key TairString的key，用于指定作为命令调用对象的TairString。 newvalue 当version和key的现有版本值相等时，将value修改为newvalue。 version 用于跟key的现有版本值比较的值。 - 返回值
- 成功：["OK", "", version]。返回值中间的""为无意义的空字符串，version为key当前的版本。
- 失败：["ERR update version is stale", value, version]。value和version为key当前的value和版本。
- 其它情况返回异常。
- 使用示例
127.0.0.1:6379> EXSET foo bar OK 127.0.0.1:6379> EXCAS foo bzz 1 1) OK 2) 3) (integer) 2 127.0.0.1:6379> EXGET foo 1) "bzz" 2) (integer) 2 127.0.0.1:6379> EXCAS foo bee 1 1) ERR update version is stale 2) "bzz" 3) (integer) 2
EXCAD
- 语法
EXCAD <key> <version>
- 时间复杂度
O(1)
- 命令描述
当指定key的版本值和命令中设置的version相等时删除Key。
- 参数及选项说明
参数/选项 说明 key TairString的key，用于指定作为命令调用对象的TairString。 newvalue 当version和key的现有版本值相等时，将value修改为newvalue。 version 用于跟key的现有版本值比较的值。 - 返回值
- 成功：1。
- key不存在：-1。
- 失败：0。
- 其它情况返回异常。
- 使用示例
127.0.0.1:6379> EXSET foo bar OK 127.0.0.1:6379> EXGET foo 1) "bar" 2) (integer) 1 127.0.0.1:6379> EXCAD not-exists 1 (integer) -1 127.0.0.1:6379> EXCAD foo 0 (integer) 0 127.0.0.1:6379> EXCAD foo 1 (integer) 1 127.0.0.1:6379> EXGET foo (nil)
