全部产品
Search
文档中心

云数据库 Redis:Roaring

更新时间:Sep 24, 2024

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

TairRoaring简介

Bitmap(又名Bitset)是一种常用的数据结构,使用少量的存储空间来实现海量数据的查询优化。尽管Bitmap相比常规基于Hash结构的实现节省了大量内存空间,但是常规Bitmap对于稀疏场景下的数据存储仍不够友好,因此有了各种压缩Bitmap的实现(Compressed 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版本,请将小版本升级至1.7.20及以上。

  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内存型,且小版本为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。

选项

  • destkey:集合运算结果所存储的目标Key(TairRoaring数据结构)。

  • operation:集合运算类型,取值:AND(表示与)、OR(表示或)、XOR(表示异或)、NOT(表示非)、DIFF(表示差)。

    说明
    • NOT仅支持操作1个对象。

    • DIFF仅支持计算2个对象的差集,请注意计算差集对象的运算顺序,例如TR.BITOP result DIFF key1 key2是计算key1关于key2的差集(key1 - key2)。

  • key:Key名称(TairRoaring数据结构),可传入多个Key。

返回值

  • 执行成功:返回操作运算结果中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。

选项

  • operation:集合运算类型,取值:AND(表示与)、OR(表示或)、XOR(表示异或)、NOT(表示非)、DIFF(表示差)。

    说明
    • NOT仅支持操作1个对象。

    • DIFF仅支持计算2个对象的差集,请注意计算差集对象的运算顺序,例如TR.BITOP result DIFF key1 key2是计算key1关于key2的差集(key1 - key2)。

  • key:Key名称(TairRoaring数据结构),可传入多个Key。

返回值

  • 执行成功:返回操作运算结果中bit值为1的数量,格式为Integer(整数)。

  • 其他情况返回相应的异常信息。

示例

命令示例:

TR.BITOPCARD NOT foo

返回示例:

(integer) 2

TR.OPTIMIZE

类别

说明

语法

TR.OPTIMIZE key

时间复杂度

O(M)

命令描述

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

选项

  • Key:Key名称(TairRoaring数据结构)。

返回值

  • 执行成功:返回OK。

  • 若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版之后将不会产生该报错。