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

TairString简介

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

主要特性
  • value携带版本号。
  • 使用INCRBYINCRBYFLOAT递增数据时可设置变更范围。

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

最佳实践

前提条件

实例为Tair内存型持久内存型(小版本为1.2.3及以上)。

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

注意事项

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

说明 Tair实例中可同时设置Redis String(即Redis原生String)和TairString,本文的命令无法对Redis String使用。

命令列表

表 1. TairString命令
命令语法简介
EXSETEXSET key value [EX|PX|EXAT|PXAT time] [NX|XX] [VER|ABS version] [KEEPTTL]

若key不存在,则创建新的key,并将value保存到key中;若key已存在,则覆盖原来value的值。

EXGETEXGET key

获取TairString的value和version。

EXSETVEREXSETVER key version

设置目标key的version。

EXINCRBYEXINCRBY key num [EX|PX|EXAT|PXAT time] [NX|XX] [VER|ABS version] [MIN minval] [MAX maxval] [KEEPTTL]

对TairString的value进行自增自减操作,num的范围为long。

EXINCRBYFLOATEXINCRBYFLOAT key num [EX|PX|EXAT|PXAT time] [NX|XX] [VER|ABS version] [MIN minval] [MAX maxval] [KEEPTTL]

对TairString的value进行自增自减操作,num的范围为double。

EXCASEXCAS key newvalue version

当目标key的version值与指定的version相等时,则更新key的value值;version不相等,则返回旧的value和version。

EXCADEXCAD key version

当目标key的version值与指定的version相等时,则删除Key。

DELDEL 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信息),该参数不能与EXPXEXATPXAT参数同时设置。
    说明 若未设置KEEPTTL参数,也未设置EXPX等设置过期时间的参数,则该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原本设置的过期时间,该参数不能与EXPXEXATPXAT参数同时设置。
    说明 若未设置KEEPTTL参数,也未设置EXPX等设置过期时间的参数,则该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原本设置的过期时间,该参数不能与EXPXEXATPXAT参数同时设置。
    说明 若未设置KEEPTTL参数,也未设置EXPX等设置过期时间的参数,则该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