TairString数据有哪些支持的命令 - 云原生内存数据库Tair

TairString（exString）是一种带版本号的String类型数据结构，本文介绍TairString数据支持的命令。

TairString简介

Redis的String仅由key和value组成，而TairString不仅包含key和value，还携带了版本（version），可用于乐观锁等场景。除此之外，TairString在Redis String加减功能的基础上支持了边界设置，可以将INCRBY、INCRBYFLOAT的结果限制在一定的范围内，超出范围则提示错误。

主要特性

value携带版本号。
使用INCRBY、INCRBYFLOAT递增数据时可设置变更范围。

该Module已开源，更多信息请参见TairString。

最佳实践

前提条件

实例为Tair内存型或持久内存型（小版本为1.2.3及以上）。

说明

最新小版本将提供更丰富的功能与稳定的服务，建议将实例的小版本升级到最新，具体操作请参见升级小版本。如果您的实例为集群实例或读写分离架构，请将代理节点的小版本也升级到最新，否则可能出现命令无法识别的情况。

注意事项

本文的操作对象为Tair实例中的TairString数据。

说明

Tair实例中可同时设置Redis String（即Redis原生String）和TairString，本文的命令无法对Redis String使用。

命令列表

表 1. TairString命令

命令	语法	简介
EXSET	`EXSET key value [EX\|PX\|EXAT\|PXAT time] [NX\|XX] [VER\|ABS version] [KEEPTTL]`	若key不存在，则创建新的key，并将value保存到key中；若key已存在，则覆盖原来value的值。
EXGET	`EXGET key`	获取TairString的value和version。
EXSETVER	`EXSETVER key version`	设置目标key的version。
EXINCRBY	`EXINCRBY key num [EX\|PX\|EXAT\|PXAT time] [NX\|XX] [VER\|ABS version] [MIN minval] [MAX maxval] [KEEPTTL]`	对TairString的value进行自增自减操作，num的范围为long。
EXINCRBYFLOAT	`EXINCRBYFLOAT key num [EX\|PX\|EXAT\|PXAT time] [NX\|XX] [VER\|ABS version] [MIN minval] [MAX maxval] [KEEPTTL]`	对TairString的value进行自增自减操作，num的范围为double。
EXCAS	`EXCAS key newvalue version`	当目标key的version值与指定的version相等时，则更新key的value值；version不相等，则返回旧的value和version。
EXCAD	`EXCAD key version`	当目标key的version值与指定的version相等时，则删除Key。
DEL	`DEL key [key ...]`	使用原生Redis的DEL命令可以删除一条或多条TairString数据。

说明

本文的命令语法定义如下：

大写关键字：命令关键字。
斜体：变量。
[options]：可选参数，不在括号中的参数为必选。
A|B：该组参数互斥，请进行二选一或多选一。
...：前面的内容可重复。

EXSET

类别	说明
语法	`EXSET key value [EX\|PX\|EXAT\|PXAT time] [NX\|XX] [VER\|ABS version] [KEEPTTL]`
时间复杂度	O(1)
命令描述	若key不存在，则创建新的key，并将value保存到key中；若key已存在，则覆盖原来value的值。
选项	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的版本号覆盖为该选项中设置的值。 KEEPTTL：延用该key原本设置的过期时间（Time to live，TTL信息），该参数不能与EX、PX、EXAT、PXAT参数同时设置。说明若未设置KEEPTTL参数，也未设置EX、PX等设置过期时间的参数，则该key的过期时间将被删除，即表示该key不会过期。
返回值	执行成功：OK。指定了XX且key不存在：nil。指定了NX且key已经存在：nil。其它情况返回相应的异常信息。
示例	命令示例： `EXSET foo bar EX 10 NX ABS 100` 返回示例： `OK`

EXGET

类别	说明
语法	`EXGET key`
时间复杂度	O(1)
命令描述	获取TairString的value和version。
选项	Key：TairString的key，用于指定作为命令调用对象的TairString。
返回值	执行成功：value与version。其它情况返回相应的异常信息。
示例	命令示例： `EXGET foo` 返回示例： `1) "bar" 2) (integer) 1`

EXSETVER

类别	说明
语法	`EXSETVER key version`
时间复杂度	O(1)
命令描述	设置目标key的version。
选项	Key：TairString的key，用于指定作为命令调用对象的TairString。 version：需要设置的版本号。
返回值	执行成功：1。若key不存在：0。其它情况返回相应的异常信息。
示例	命令示例： `EXSETVER foo 2` 返回示例： `(integer) 1`

EXINCRBY

类别	说明
语法	`EXINCRBY key num [EX\|PX\|EXAT\|PXAT time] [NX\|XX] [VER\|ABS version] [MIN minval] [MAX maxval] [KEEPTTL]`
时间复杂度	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的最大值。 KEEPTTL：延用该key原本设置的过期时间，该参数不能与EX、PX、EXAT、PXAT参数同时设置。说明若未设置KEEPTTL参数，也未设置EX、PX等设置过期时间的参数，则该key的过期时间将被删除，即表示该key不会过期。
返回值	执行成功：操作后value的值。若设置了MAX或MIN，而操作后的value超过了该范围：(error) ERR increment or decrement would overflow。其它情况返回相应的异常信息。
示例	提前执行`EXSET foo 1`命令。命令示例： `EXINCRBY foo 100 MAX 300` 返回示例： `(integer) 101`

EXINCRBYFLOAT

类别	说明
语法	`EXINCRBYFLOAT key num [EX\|PX\|EXAT\|PXAT time] [NX\|XX] [VER\|ABS version] [MIN minval] [MAX maxval] [KEEPTTL]`
时间复杂度	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：只在key不存在时写入。 XX：只在key存在时写入。 VER：版本号。如果key存在，和当前版本号做比较：如果相等，进行自增，且版本号加1。如果不相等，返回异常。如果key不存在或者key当前版本为0，忽略传入的版本号并进行自增操作，成功后版本号变为1。 ABS：绝对版本号。设置后，无论key当前的版本号是多少，完成写入并将key的版本号覆盖为该选项中设置的值。 MIN：设置TairString value的最小值。 MAX：设置TairString value的最大值。 KEEPTTL：延用该key原本设置的过期时间，该参数不能与EX、PX、EXAT、PXAT参数同时设置。说明若未设置KEEPTTL参数，也未设置EX、PX等设置过期时间的参数，则该key的过期时间将被删除，即表示该key不会过期。
返回值	执行成功：操作后value的值。若设置了MAX或MIN，而操作后的value超过了该范围：(error) ERR increment or decrement would overflow。其它情况返回相应的异常信息。
示例	提前执行`EXSET foo 1`命令。命令示例： `EXINCRBYFLOAT foo 10.123` 返回示例： `(integer) 11.123`

EXCAS

类别	说明
语法	`EXCAS key newvalue version`
时间复杂度	O(1)
命令描述	当目标key的version值与指定的version相等时，则更新key的value值；version不相等，则返回旧的value和version。
选项	Key：TairString的key，用于指定作为命令调用对象的TairString。 newvalue：若key的version值与指定的version相等，将value修改为newvalue。 version：用于跟key的现有version值比较的值。
返回值	执行成功：["OK", "",最新的version]。中间的""为无意义的空字符串。执行失败：["ERR update version is stale", value, version]。value和version为key当前的value和版本。若key不存在：-1。其它情况返回相应的异常信息。
示例	提前执行`EXSET foo bar`命令。命令示例： `EXCAS foo bzz 1` 返回示例： `1) OK 2) 3) (integer) 2`

EXCAD

类别	说明
语法	`EXCAD key version`
时间复杂度	O(1)
命令描述	当目标key的version值与指定的version相等时，则删除Key。
选项	Key：TairString的key，用于指定作为命令调用对象的TairString。 version：用于跟key的现有version值比较的值。
返回值	执行成功：1。执行失败：0。若key不存在：-1。其它情况返回相应的异常信息。
示例	提前执行`EXSET foo bar`命令。命令示例： `EXCAD foo 1` 返回示例： `(integer) 1`