TairRoaring是基于Tair引擎的Roaring Bitmap实现,本文介绍TairRoaring及其支持的命令。

TairRoaring简介

Bitmap(又名Bitset)是一种常用的数据结构,使用少量的存储空间来实现海量数据的查询优化。尽管Bitmap相比常规基于Hash结构的实现节省了大量内存空间,但是常规Bitmap对于稀疏场景下的数据存储仍不够友好,因此有了各种压缩Bitmap的实现(Comprised bitmap),Roaring Bitmap就是业界公认的一种更高效和均衡的Bitmap压缩存储的实现。

TairRoaring在此基础上完成大量优化:
  • 通过2层索引和多种动态容器(Container),平衡了多种场景下性能和空间效率。
  • 使用了包括SIMD instructions、Vectorization、PopCnt算法等多种工程优化,提升了计算效率,实现了高效的时空效率。
  • 基于Tair提供的强大计算性能和极高的稳定性,为用户场景保驾护航。
典型场景

适用于直播、音乐、电商等行业,通过用户多维度标签,进行个性化推荐、精准营销等场景。

发布记录
重要 V2版本Breaking Change公告:
  • TR.RANGEINTARRAY:V1版本的TR.RANGEINTARRAY命令名称修改为V2版本的TR.RANGE,其内容无变化。
  • TR.SETRANGE:V1版本的TR.SETRANGE命令的返回值为OK,V2版本返回值为成功设置bit值为1的数量,其他内容无变化。
  1. 2021年9月13日发布TairRoaring V1版本
  2. 2022年3月11日发布TairRoaring V2版本 版本,请将小版本升级至1.7.27及以上。

    该版本优化了部分命令的实现,提升了性能。新增TR.SETBITS、TR.CLEARBITS等9个命令,向前兼容扩展2个命令,更新1个命令,更名1个命令。

  3. 2022年4月20日发布TairRoaring V2.2版本 版本,请将小版本升级至1.8.1及以上。

    该版本新增TR.JACCARD、TR.CONTAINS、TR.RANK命令,更新部分命令在key不存在时的返回错误(移除了ERR key not found)。

最佳实践

基于TairRoaring实现人群圈选方案

前提条件

实例为Tair(Redis企业版)内存型,且小版本为1.7.7及以上。
说明 最新小版本将提供更丰富的功能与稳定的服务,建议将实例的小版本升级到最新,具体操作请参见升级小版本

注意事项

操作对象为Tair实例中的TairRoaring数据。

命令列表

类型 命令 语法 说明 版本变更
写操作 TR.SETBIT TR.SETBIT key offset value

设置Roaring Bitmap中指定偏移量(offset)的bit值(1或者0),并返回该bit位之前的值,Roaring Bitmap的偏移量(offset)从0开始。

-(表示未更新)
TR.SETBITS TR.SETBITS key offset [offset1 offset2 ... offsetN]

设置Roaring Bitmap中指定偏移量(offset)的bit值为1,支持传入多个值。

V2新增
TR.CLEARBITS TR.CLEARBITS key offset [offset1 offset2 ... offsetN]

设置Roaring Bitmap中指定偏移量(offset)的bit值为0,若原值为0则不操作,支持传入多个值。

V2新增
TR.SETRANGE TR.SETRANGE key start end

设置Roaring Bitmap中指定区间(偏移量)的bit值为1。

V2更新,更新返回值为成功设置bit值为1的数量。
TR.APPENDBITARRAY TR.APPENDBITARRAY key offset bitarray

将由连续的0或1组成的bit数组(bitarray)插入到Roaring Bitmap中指定偏移量(offset)之后的位置,并覆盖原有数据。

V2新增
TR.FLIPRANGE TR.FLIPRANGE key start end

对Roaring Bitmap中指定区间(偏移量)的bit值执行位反转(1反转为0;0反转为1)。若指定key不存在,则自动创建目标key,并以空Roaring Bitmap对指定区间的bit值执行位反转。

V2新增
TR.APPENDINTARRAY TR.APPENDINTARRAY key value [value1 value2 ... valueN]
设置Roaring Bitmap中指定偏移量(offset)的bit值为1,支持传入多个值。
说明 在TairRoaring V2版本中,建议使用TR.SETBITS代替该命令。
-
TR.SETINTARRAY TR.SETINTARRAY key value [value1 value2 ... valueN]
根据传入的整型数组,创建对应的Roaring Bitmap,该命令会重置(覆盖)已存在的Roaring Bitmap对象。
说明 在TairRoaring V2版本中,建议使用TR.SETBITS代替该命令。
-
TR.SETBITARRAY TR.SETBITARRAY key value
根据传入的bit(由0和1组成的字符串),创建对应的Roaring Bitmap。若目标Key已存在则会重置(覆盖)原有数据。
说明 在TairRoaring V2版本中,建议使用TR.APPENDBITARRAY代替该命令。
-
TR.BITOP TR.BITOP destkey operation key [key1 key2 ... keyN]
对Roaring Bitmap执行集合运算操作,计算结果存储在destkey中,支持ANDORXORNOTDIFF集合运算类型。
说明 该命令在集群架构实例中不支持执行跨Slot的Key。
-
TR.BITOPCARD TR.BITOPCARD operation key [key1 key2 ... keyN]
对Roaring Bitmap执行集合运算操作,支持ANDORXORNOTDIFF集合运算类型。
说明 该命令在集群架构实例中不支持执行跨Slot的Key。
V2新增
TR.OPTIMIZE TR.OPTIMIZE key

优化Roaring Bitmap的存储空间。如果目标对象相对较大,且创建后以只读操作为主,可以主动执行此命令。

-
读操作 TR.GETBIT TR.GETBIT key offset

获取Roaring Bitmap中指定偏移量(offset)的bit值。

-
TR.GETBITS TR.GETBITS key offset [offset1 offset2 ... offsetN]

获取Roaring Bitmap中指定偏移量(offset)的bit值,支持查询多个值。

V2新增
TR.BITCOUNT TR.BITCOUNT key [start end]

获取Roaring Bitmap中指定区间(偏移量)bit值为1的数量。

V2更新,向前兼容。
TR.BITPOS TR.BITPOS <key> <value> [count]

获取第count个bit值为1或者0的偏移量,count为可选参数,默认为1(表示从前向后计数的第一个)。

V2更新,向前兼容。
TR.SCAN TR.SCAN key start_offset [COUNT count]
从Roaring Bitmap中指定偏移量(start_offset)开始向后扫描,返回若干(count)个bit值为1的偏移量,返回的游标(cursor)为Roaring Bitmap对应的offset。
说明 在迭代过程中被添加、被删除的元素的扫描结果存在不确定性,即可能被返回,也可能不会。
V2新增
TR.RANGE TR.RANGE key start end

获取Roaring Bitmap指定区间中bit值为1的偏移量。

V1的TR.RANGEINTARRAY命令,V2重命名为TR.RANGE。
TR.RANGEBITARRAY TR.RANGEBITARRAY key start end

获取Roaring Bitmap指定区间中所有bit值(0、1)组成的字符串。

V2新增
TR.MIN TR.MIN key

获取Roaring Bitmap中bit值为1的最小偏移量(首个),不存在时返回-1。

-
TR.MAX TR.MAX key

获取Roaring Bitmap中bit值为1的最大偏移量,不存在时返回-1。

-
TR.STAT TR.STAT key [JSON]

获取Roaring Bitmap的统计信息,包括各种容器的数量以及内存使用状况等信息。

V2新增
TR.JACCARD TR.JACCARD key1 key2
获取两个Roaring Bitmap之间的Jaccard相似系数,Jaccard系数值越大,Roaring Bitmap的相似度越高。
说明 该命令在集群架构实例中不支持执行跨Slot的Key。
V2.2新增
TR.CONTAINS TR.CONTAINS key1 key2
计算key2所对应的Roaring Bitmap是否包含key1所对应的Roaring Bitmap(即key1是否为key2的子集),若包含则返回1,否则返回0。
说明 该命令在集群架构实例中不支持执行跨Slot的Key。
V2.2新增
TR.RANK TR.RANK key offset

获取Roaring Bitmap中从offset为0到指定offset区间内(包含该值),bit值为1的数量。

V2.2新增
通用 DEL DEL key [key ...] 使用原生Redis的DEL命令可以删除一条或多条TairRoaring数据。 -
说明
  • 本文关于命令语法的定义:
    • 大写关键字:命令关键字。
    • 斜体:变量。
    • [options]:可选参数,不在括号中的参数为必选。
    • A|B:该组参数互斥,请进行二选一或多选一。
    • ...:前面的内容可重复。
  • 本文关于 时间复杂度 的特别约定:
    • C表示参数的数量(argc)或范围(range)。
    • M表示该种数据结构内部bit值为1的数量(例如List的node数量,Hash的field数量等)。

TR.SETBIT

类别 说明
语法 TR.SETBIT key offset value
时间复杂度 O(1)
命令描述

设置Roaring Bitmap中指定偏移量(offset)的bit值(1或者0),并返回该bit位之前的值,Roaring Bitmap的偏移量(offset)从0开始。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • offset:整型数字,表示待设置bit的偏移量,取值范围为0 ~ 2^32。
  • value:待设置的bit值,可以设置1或者0。
返回值
  • 执行成功:返回0或1,表示bit位之前的值。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.SETBIT foo 0 1

返回示例:

(integer) 0

TR.SETBITS

类别 说明
语法 TR.SETBITS key offset [offset1 offset2 ... offsetN]
时间复杂度 O(C)
命令描述

设置Roaring Bitmap中指定偏移量(offset)的bit值为1,支持传入多个值。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • offset:整型数字,表示待设置bit的偏移量,取值范围为0 ~ 2^32。
返回值
  • 执行成功:返回更新后Roaring Bitmap中bit值为1的数量。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.SETBITS foo 9 10

返回示例:

(integer) 5

TR.CLEARBITS

类别 说明
语法 TR.CLEARBITS key offset [offset1 offset2 ... offsetN]
时间复杂度 O(C)
命令描述

设置Roaring Bitmap中指定偏移量(offset)的bit值为0,若原值为0则不操作,支持传入多个值。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • offset:整型数字,表示待设置bit的偏移量,取值范围为0 ~ 2^32。
返回值
  • 执行成功:返回本次命令成功将bit值设置为0的数量。
  • 若key不存在:返回0。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.CLEARBITS foo 9 10

返回示例:

(integer) 2

TR.SETRANGE

类别 说明
语法 TR.SETRANGE key start end
时间复杂度 O(C)
命令描述

设置Roaring Bitmap中指定区间(偏移量)的bit值为1。

例如执行TR.SETRANGE foo 1 3,将创建foo为"0111"。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • start:起始偏移量(包含该值),取值范围为0 ~ 2^32。
  • end:结束偏移量(包含该值),取值范围为0 ~ 2^32。
返回值
  • 执行成功:返回本次命令成功将bit值设置为1的数量。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.SETRANGE foo 1 3

返回示例:

(integer) 3

TR.APPENDBITARRAY

类别 说明
语法 TR.APPENDBITARRAY key offset bitarray
时间复杂度 O(C)
命令描述

将由连续的0或1组成的bit数组(bitarray)插入到Roaring Bitmap中指定偏移量(offset)之后的位置,并覆盖原有数据。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • offset:指定的起始偏移量(不包含该值),取值范围为-1 ~ 2^32。
  • bitarray:待添加的bit数组,将覆盖原有数据,由连续的0或1,取值范围为0 ~ 2^32。
    说明 指定的offset与添加的bitarray的总长度不能超过2^32,否则会操作失败。
返回值
  • 执行成功:返回本次命令成功将bit值设置为1的数量。
  • 其他情况返回相应的异常信息。
示例

提前执行TR.SETBITS foo 0

命令示例:

TR.APPENDBITARRAY foo 1 1101

返回示例:

(integer) 4

此时,Roaring Bitmap foo为“101101”。

TR.FLIPRANGE

类别 说明
语法 TR.FLIPRANGE key start end
时间复杂度 O(C)
命令描述

对Roaring Bitmap中指定区间(偏移量)的bit值执行位反转(1反转为0;0反转为1)。若指定key不存在,则自动创建目标key,并以空Roaring Bitmap对指定区间的bit值执行位反转。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • start:起始偏移量(包含该值),取值范围为0 ~ 2^32。
  • end:结束偏移量(包含该值),取值范围为0 ~ 2^32。
返回值
  • 执行成功:返回本次命令成功将bit值设置为1的数量。
  • 若key不存在:自动创建目标key,并以空Roaring Bitmap对指定区间的bit值执行位反转,返回本次命令成功将bit值设置为1的数量。
  • 其他情况返回相应的异常信息。
示例

提前执行TR.SETBITS foo 0 2 3 5

命令示例:

TR.FLIPRANGE foo 0 5

返回示例:

(integer) 2

此时,Roaring Bitmap foo为“01001”。

TR.APPENDINTARRAY

类别 说明
语法 TR.APPENDINTARRAY key value [value1 value2 ... valueN]
时间复杂度 O(C)
命令描述
设置Roaring Bitmap中指定偏移量(offset)的bit值为1,支持传入多个值。
说明 在TairRoaring V2版本中,建议使用TR.SETBITS代替该命令。
选项
  • Key:Key名称(TairRoaring数据结构)。
  • value:整型数字,表示待设置的bit位,取值范围为0 ~ 4294967296。
返回值
  • 执行成功:返回OK。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.APPENDINTARRAY foo 9 10

返回示例:

OK

TR.SETINTARRAY

类别 说明
语法 TR.SETINTARRAY key value [value1 value2 ... valueN]
时间复杂度 O(C)
命令描述
根据传入的整型数组来设置对应的Roaring Bitmap,若目标Key已存在则会重置(覆盖)原有数据。
说明 在TairRoaring V2版本中,建议使用TR.SETBITS代替该命令。
选项
  • Key:Key名称(TairRoaring数据结构)。
  • value:整型数字,表示待设置的bit位。
返回值
  • 执行成功:返回OK。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.SETINTARRAY foo 2 4 5 6

返回示例:

OK

TR.SETBITARRAY

类别 说明
语法 TR.SETBITARRAY key value
时间复杂度 O(C)
命令描述
根据传入的bit(由0和1组成的字符串),创建对应的Roaring Bitmap。若目标Key已存在则会重置(覆盖)原有数据。
说明 在TairRoaring V2版本中,建议使用TR.APPENDBITARRAY代替该命令。
选项
  • key:Key名称(TairRoaring数据结构)。
  • value:由0和1构成的字符串,即需要设置的bit数组。
返回值
  • 执行成功:返回OK
  • 其他情况返回相应的异常信息。
示例

命令示例:

tr.setbitarray foo 10101001

返回示例:

OK 

TR.BITOP

类别 说明
语法 TR.BITOP destkey operation key [key1 key2 ... keyN]
时间复杂度 O(C * M)
命令描述
对Roaring Bitmap执行集合运算操作,计算结果存储在destkey中,支持ANDORXORNOTDIFF集合运算类型。
说明 该命令在集群架构实例中不支持执行跨Slot的Key。
选项
  • key:Key名称(TairRoaring数据结构),可传入多个Key。
  • operation:集合运算类型,取值:AND(表示与)、OR(表示或)、XOR(表示异或)、NOT(表示非)、DIFF(表示差)。
    说明
    • NOT仅支持操作1个对象。
    • DIFF仅支持计算2个对象的差集,请注意计算差集对象的运算顺序,例如TR.BITOP result DIFF key1 key2是计算key1关于key2的差集(key1 - key2)。
  • destkey:集合运算结果所存储的目标Key(TairRoaring数据结构)。
返回值
  • 执行成功:返回操作运算结果中bit值为1的数量,格式为Integer(整数)。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.BITOP result OR foo bar

返回示例:

(integer) 6

TR.BITOPCARD

类别 说明
语法 TR.BITOPCARD operation key [key1 key2 ... keyN]
时间复杂度 O(C * M)
命令描述
对Roaring Bitmap执行集合运算操作,支持ANDORXORNOTDIFF集合运算类型。
说明 该命令在集群架构实例中不支持执行跨Slot的Key。
选项
  • key:Key名称(TairRoaring数据结构),可传入多个Key。
  • operation:集合运算类型,取值:AND(表示与)、OR(表示或)、XOR(表示异或)、NOT(表示非)、DIFF(表示差)。
    说明
    • NOT仅支持操作1个对象。
    • DIFF仅支持计算2个对象的差集,请注意计算差集对象的运算顺序,例如TR.BITOP result DIFF key1 key2是计算key1关于key2的差集(key1 - key2)。
返回值
  • 执行成功:返回操作运算结果中bit值为1的数量,格式为Integer(整数)。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.BITOPCARD NOT foo

返回示例:

(integer) 2

TR.OPTIMIZE

类别 说明
语法 TR.OPTIMIZE key
时间复杂度 O(M)
命令描述

优化Roaring Bitmap的存储空间。如果目标对象相对较大,且创建后以只读操作为主,可以主动执行此命令。

选项
  • Key:Key名称(TairRoaring数据结构)。
返回值
  • 执行成功:返回更新后Roaring Bitmap中bit值为1的数量。
  • 若key不存在:返回nil
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.OPTIMIZE foo

返回示例:

OK

TR.GETBIT

类别 说明
语法 TR.GETBIT key offset
时间复杂度 O(1)
命令描述

获取Roaring Bitmap中指定偏移量(offset)的bit值。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • offset:待查询的偏移量。
返回值
  • 执行成功:返回0或1,表示bit位的值。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.GETBIT foo 0

返回示例:

(integer) 1

TR.GETBITS

类别 说明
语法 TR.GETBITS key offset [offset1 offset2 ... offsetN]
时间复杂度 O(C)
命令描述

获取Roaring Bitmap中指定偏移量(offset)的bit值,支持查询多个值。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • offset:待查询的偏移量。
返回值
  • 执行成功:返回对应bit的值。
  • 若key不存在:返回空数组。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.GETBITS foo 3 4 6 8

返回示例:

1) (integer) 1
2) (integer) 1
3) (integer) 1
4) (integer) 0

TR.BITCOUNT

类别 说明
语法 TR.BITCOUNT key [start end]
时间复杂度 O(M)
命令描述

获取Roaring Bitmap中指定区间(偏移量)bit值为1的数量。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • start:起始偏移量(包含该值),取值范围为0 ~ 2^32。
  • end:结束偏移量(包含该值),取值范围为0 ~ 2^32。
返回值
  • 执行成功:返回Roaring Bitmap中值为1的bit位数量,格式为Integer(整数)。
  • 若key不存在:返回0。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.BITCOUNT foo 4 9

返回示例:

(integer) 3

TR.BITPOS

类别 说明
语法 TR.BITPOS <key> <value> [count]
时间复杂度 O(C)
命令描述

获取第count个bit值为1或者0的偏移量,count为可选参数,默认为1(表示从前向后计数的第一个)。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • value:待查找bit值(1或者0)。
  • count:查找第几位,负数表示从末尾向前计数。
返回值
  • 执行成功:返回目标bit的偏移量(offset)。
  • 若key不存在:返回-1。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.BITPOS foo 1 -1

返回示例:

(integer) 6

TR.SCAN

类别 说明
语法 TR.SCAN key start_offset [COUNT count]
时间复杂度 O(C)
命令描述
从Roaring Bitmap中指定偏移量(start_offset)开始向后扫描,返回若干(count)个bit值为1的偏移量,返回的游标(cursor)为Roaring Bitmap对应的offset。
说明 在迭代过程中被添加、被删除的元素的扫描结果存在不确定性,即可能被返回,也可能不会。
选项
  • Key:Key名称(TairRoaring数据结构)。
  • start_offset:起始偏移量(包含该值)。
  • COUNT:查询的数量(默认为10)。
返回值
  • 执行成功,返回具有两个元素的数组:
    • 第一个元素:下次查询的start_offset,若该key已扫描完成,则返回0。
    • 第二个元素:本次查询的目标偏移量。
    说明 若key不存在,返回0与空元素组成的数组。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.SCAN foo 0 COUNT 2

返回示例:

1) (integer) 3
2) 1) (integer) 0
   2) (integer) 2

TR.RANGE

类别 说明
语法 TR.RANGE key start end
时间复杂度 O(C)
命令描述

获取Roaring Bitmap指定区间中bit值为1的偏移量。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • start:起始的偏移量(包含该值)。
  • end:结束的偏移量(包含该值)。
返回值
  • 执行成功:返回bit值为1的偏移量。
  • 若key不存在:返回空数组。
  • 其他情况返回相应的异常信息。
示例

提前执行TR.SETBITS foo 0 2 3 5

命令示例:

TR.RANGE foo 0 5

返回示例:

1) (integer) 0
2) (integer) 2
3) (integer) 3
4) (integer) 5

TR.RANGEBITARRAY

类别 说明
语法 TR.RANGEBITARRAY key start end
时间复杂度 O(C)
命令描述

获取Roaring Bitmap指定区间中所有bit值(0、1)组成的字符串。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • start:起始的偏移量(包含该值)。
  • end:结束的偏移量(包含该值)。
返回值
  • 执行成功:返回bit值为1的偏移量。
  • 若key不存在:返回nil
  • 其他情况返回相应的异常信息。
示例

提前执行TR.SETBITS foo 0 2 3 5

命令示例:

TR.RANGEBITARRAY foo 0 5

返回示例:

"101101"

TR.MIN

类别 说明
语法 TR.MIN key
时间复杂度 O(1)
命令描述

获取Roaring Bitmap中bit值为1的最小偏移量(首个),不存在时返回-1。

选项
  • Key:Key名称(TairRoaring数据结构)。
返回值
  • 执行成功:
    • 返回首个bit值为1的偏移量,格式为Integer(整数)。
    • 返回-1,表示key不存在或者该Roaring Bitmap中不存在值为1的bit。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.MIN foo

返回示例:

4

TR.MAX

类别 说明
语法 TR.MAX key
时间复杂度 O(1)
命令描述

获取Roaring Bitmap中bit值为1的最大偏移量,不存在时返回-1。

选项
  • Key:Key名称(TairRoaring数据结构)。
返回值
  • 执行成功:
    • 返回最后一个bit值为1的偏移量,格式为Integer(整数)。
    • 返回-1,表示key不存在或者该Roaring Bitmap中不存在值为1的bit。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.MAX foo

返回示例:

6

TR.STAT

类别 说明
语法 TR.STAT key [JSON]
时间复杂度 O(M)
命令描述

获取Roaring Bitmap的统计信息,包括各种容器的数量以及内存使用状况等信息。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • JSON:若指定JSON,则以JSON格式返回统计信息。
返回值
  • 执行成功:返回Redis的统计信息(bulk string),说明如下。
    "{\"cardinality\":3,                    # 元素总数量
    \"number_of_containers\":1,             # TairRoaring容器总数(Roaring Bitmap概念)
    \"max_value\":6,                        # 最大元素值
    \"min_value\":3,                        # 最小元素值
    \"sum_value\":13,
    \"array_container\":{                   # array容器数量(Roaring Bitmap概念)
        \"number_of_containers\":1,
        \"container_cardinality\":3,
        \"container_allocated_bytes\":6},
    \"bitset_container\":{                  # bitset容器数量(Roaring Bitmap概念)
        \"number_of_containers\":0,
        \"container_cardinality\":0,
        \"container_allocated_bytes\":0},
    \"run_container\":{                     # RLE容器数量(Roaring Bitmap概念)
        \"number_of_containers\":0,
        \"container_cardinality\":0,
        \"container_allocated_bytes\":0}}"
    
                                            
  • 若key不存在:返回nil
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.STAT foo JSON

返回示例:

"{\"cardinality\":4,\"number_of_containers\":1,\"max_value\":5,\"min_value\":0,\"sum_value\":10,\"array_container\":{\"number_of_containers\":1,\"container_cardinality\":4,\"container_allocated_bytes\":8},\"bitset_container\":{\"number_of_containers\":0,\"container_cardinality\":0,\"container_allocated_bytes\":0},\"run_container\":{\"number_of_containers\":0,\"container_cardinality\":0,\"container_allocated_bytes\":0}}"

TR.JACCARD

类别 说明
语法 TR.JACCARD key1 key2
时间复杂度 O(M)
命令描述
获取两个Roaring Bitmap之间的Jaccard相似系数,Jaccard系数值越大,Roaring Bitmap的相似度越高。
说明 该命令在集群架构实例中不支持执行跨Slot的Key。
选项
  • Key:Key名称(TairRoaring数据结构)。
返回值
  • 执行成功:返回Jaccard相似系数(Double类型)。
  • 其他情况返回相应的异常信息。
示例

命令示例:

TR.JACCARD foo1 foo2

返回示例:

"0.20000000000000001"

TR.CONTAINS

类别 说明
语法 TR.CONTAINS key1 key2
时间复杂度 O(M)
命令描述
计算key2所对应的Roaring Bitmap是否包含key1所对应的Roaring Bitmap(即key1是否为key2的子集),若包含则返回1,否则返回0。
说明 该命令在集群架构实例中不支持执行跨Slot的Key。
选项
  • Key:Key名称(TairRoaring数据结构)。
返回值
  • 执行成功:
    • 返回1,表示key2包含key1,即key1是key2的子集。
    • 返回0,表示key2不包含key1,即key1不是key2的子集。
  • 其他情况返回相应的异常信息。
示例

提前执行TR.SETBITS fooM 1 2 3 10TR.SETBITS foom 1 2命令。

命令示例:

TR.CONTAINS foom fooM

返回示例:

(integer) 1

TR.RANK

类别 说明
语法 TR.RANK key offset
时间复杂度 O(M)
命令描述

获取Roaring Bitmap中从offset为0到指定offset区间内(包含该值),bit值为1的数量。

选项
  • Key:Key名称(TairRoaring数据结构)。
  • offset:指定bit的offset位,取值为INT(整型数字)。
返回值
  • 执行成功:目标区间bit值为1的数量。
  • 其他情况返回相应的异常信息。
示例

提前执行TR.SETBITS fooM 1 2 3 10

命令示例:

TR.RANK fooM 10

返回示例:

(integer) 4

异常返回值说明

错误信息 说明
WRONGTYPE Operation against a key holding the wrong kind of value 对象类型错误:Key不是TairRoaring对象。
ERR bad arguments, must be unsigned 32-bit integer 参数类型错误:无法按照32-bit整型进行转换。
ERR invalid arguments, maybe out of range or illegal 参数非法:
  • 非32-bit整型的offset不符合规则。
  • 参数的[start,end]不符合规则。
  • 参数超过Roaring Bitmap的元素个数。
ERR key already exist Roaring Bitmap对象已存在,且不支持覆盖。
说明 V2.2版之后将不会产生该报错。
ERR key not found Roaring Bitmap对象不存在, 不支持操作。
说明 V2.2版之后将不会产生该报错。