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命令
命令语法简介
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信息），该参数不能与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