全部产品
Search
文档中心

云原生内存数据库Tair:exString

更新时间:Jul 03, 2024

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命令

命令

语法

简介

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信息),该参数不能与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