本章节介绍TairString数据支持的命令。

TairString简介

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

主要特性:

  • value携带版本号。
  • 使用INCRBYINCRBYFLOAT递增数据时可设置变更范围。
警告 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,否则失败。
DEL DEL <key> [key ...] 使用原生Redis的DEL命令可以删除一条或多条TairString数据,详细用法请参见DEL

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)