本章节介绍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使用。

命令列表

表 1. TairString命令
命令 语法 简介
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，否则失败。

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，忽略传入的版本号直接插入field，成功后版本号变为1。
    ABS 绝对版本号。设置后，无论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的最大值。
  • 返回值
    • 成功：value的当前值。
    • 其它情况返回异常。
  • 使用示例 
    127.0.0.1:6379> EXINCRBY foo 100
(integer) 200
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的最大值。
  • 返回值
    • 成功：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)