TairString是一种带版本号的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
|