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

Tair Roaring简介

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

Tair Roaring属于高度工程优化的Bitmap实现:
  • 通过2层索引和引入多种动态容器(Container),平衡了多种场景下性能和空间效率。
  • 同时使用了包括SIMD instructions、Vectorization、PopCnt算法在内的等多种工程优化,提升了计算效率,实现了高效的时空效率。
  • 基于Tair企业版提供的强大计算性能和极高的稳定性,为用户场景保驾护航。

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

最佳实践

基于TairRoaring实现的人群圈选方案

前提条件

注意事项

操作对象为性能增强型实例中的TairRoaring数据。

命令列表

命令 语法 说明
TR.SETBIT TR.SETBIT <key> <offset> <value>

设置bitmap指定bit位的值(1或者0),并返回该bit位之前的值。

TR.GETBIT TR.GETBIT <key> <offset>

获取bitmap指定偏移量(offset)的bit位值。

TR.BITCOUNT TR.BITCOUNT <key>

计算bitmap中值为1的bit位数量。

TR.BITPOS TR.BITPOS <key> <value>

传入一个value值(1或者0),在目标Key(Tair Roaring数据结构)中查找首个被设置为指定值的bit位,并返回该bit位的偏移量(offset),偏移量(offset)从0开始。

TR.BITOP TR.BITOP <destkey> <operation> <key> [<key2> <key3>...]
对Roaring bitmap执行集合运算操作,计算结果存储在destkey中。
说明 集群架构暂不支持该命令。
TR.SETINTARRAY TR.SETINTARRAY <key> <value1> [<value2> <value3> ... <valueN>]

根据传入的整形数组来设置对应的Roaring bitmap, 该命令会覆盖已存在的Roaring bitmap对象。

TR.RANGEINTARRAY TR.RANGEINTARRAY <key> <start> <end>

获取Roaring bitmap中bit值为1所对应的int数组的元素范围,下标为元素范围的元素,如果下标超过对应int数组长度则用0补齐。

TR.APPENDINTARRAY TR.APPENDINTARRAY <key> <value1> [<value2> <value3> ... <valueN>]

将bitmap中指定bit位的值(value)设置为1,支持传入多个值。

TR.DIFF TR.DIFF <destkey> <key1> <key2>
计算key1与key2对应Roaring Bitmap的差集,并将结果储到destkey所指的键中。
说明 集群架构暂不支持该命令。
TR.SETFULL TR.SETFULL <key>

创建一个新的Key,并使用1填充整个Roaring bitmap,bit位的长度为4294967296(最大值)。

TR.SETRANGE TR.SETRANGE <key> <start> <end>

将Roaring bitmap中start到end之间的bit位设置为1,区间左闭右开。

TR.OPTIMIZE TR.OPTIMIZE <key>

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

TR.STAT TR.STAT <key>

返回当前bitmap的统计信息, 包括各种容器的数量以及内存使用状况等信息。

TR.SETBITARRAY TR.SETBITARRAY <key> <value>

根据传入的bit(由0和1组成的字符串),来创建一个位图(bitmap)。执行该命令时,Redis会逐个字符判断,只操作bit为1的字符,如果目标Key已存在则会覆盖已有数据。

TR.MIN TR.MIN <key>

返回key对应的bitmap集合中首个bit值为1的偏移量,不存在时返回-1。

TR.MAX TR.MAX <key>

返回key对应的bitmap集合中bit值为1的最大偏移量,不存在时返回-1。

本文关于 时间复杂度 的特别约定
  • C表示参数的数量(argc)或范围(range)。
  • M表示该种数据结构的内部数量(比如List的node数量,Hash的field数量等)。

TR.SETBIT

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

设置bitmap指定bit位的值(1或者0),并返回该bit位之前的值。

选项
  • Key:Key名称(Tair Roaring数据结构)。
  • offset:待操作的bit位所对应的offset,取值范围位为0 ~ 2^32。
  • value:bit位设置的值,可以设置1或者0。
返回值
  • 执行成功:返回0或1,表示bit位之前的值。
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.SETBIT foo 0 1

返回示例:

(integer) 0

TR.GETBIT

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

获取bitmap指定偏移量(offset)的bit位值。

选项
  • Key:Key名称(Tair Roaring数据结构)。
  • offset:待操作的bit位所对应的offset,取值范围位为0 ~ 2^32。
返回值
  • 执行成功:返回0或1,表示bit位的值。
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.GETBIT foo 0

返回示例:

(integer) 1

TR.BITCOUNT

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

计算bitmap中值为1的bit位数量。

选项
  • Key:Key名称(Tair Roaring数据结构)。
返回值
  • 执行成功:返回Key中值为1的bit位数量,格式为Integer(整数)。
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.BITCOUNT foo

返回示例:

(integer) 1

TR.BITPOS

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

传入一个value值(1或者0),在目标Key(Tair Roaring数据结构)中查找首个被设置为指定值的bit位,并返回该bit位的偏移量(offset),偏移量(offset)从0开始。

选项
  • Key:Key名称(Tair Roaring数据结构)。
  • value:待查找bit位的值,例如0或1。
返回值
  • 执行成功:返回目标bit位的偏移量(offset)。
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.BITPOS foo 1

返回示例:

0

TR.BITOP

类别 说明
语法 TR.BITOP <destkey> <operation> <key> [<key2> <key3>...]
时间复杂度 O(C * M)
命令描述
对Roaring bitmap执行集合运算操作,计算结果存储在destkey中。
说明 集群架构暂不支持该命令。
选项
  • key:Key名称(Tair Roaring数据结构),可传入多个Key。
  • opreation:集合运算类型,取值:AND(表示与)、OR(表示或)、NOT(表示非)XOR(表示异或)
  • destkey:集合运算结果所存储的目标Key(Tair Roaring数据结构)。
返回值
  • 执行成功:返回操作运算后的结果中bit的个数,格式为Integer(整数)。
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.BITOP result OR foo bar

返回示例:

2

TR.SETINTARRAY

类别 说明
语法 TR.SETINTARRAY <key> <value1> [<value2> <value3> ... <valueN>]
时间复杂度 O(C)
命令描述

根据传入的整形数组来设置对应的Roaring bitmap, 该命令会覆盖已存在的Roaring bitmap对象。

选项
  • Key:Key名称(Tair Roaring数据结构)。
  • value:整形数字,表示待设置的bit位。
返回值
  • 执行成功:返回OK。
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.SETINTARRAY foo 2 4 5 6

返回示例:

OK

TR.RANGEINTARRAY

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

获取Roaring bitmap中bit值为1所对应的int数组的元素范围,下标为元素范围的元素,如果下标超过对应int数组长度则用0补齐。

例如bitmap foo 101101,bit值为1对应元素数组是 [0 2 3 5],TR.RANGEINTARRAY foo 0返回[0];TR.RANGEINTARRAY foo 1 2返回[2 3];TR.RANGEINTARRAY foo 0 5返回[0 2 3 5 0 0]。

选项
  • Key:Key名称(Tair Roaring数据结构)。
  • start:起始的bit位下标,为闭区间。
  • end:结束的bit位下标,为闭区间。
返回值
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.RANGEINTARRAY foo 0 7

返回示例:

1) (integer) 2
2) (integer) 4
3) (integer) 5
4) (integer) 6
5) (integer) 0
6) (integer) 0
7) (integer) 0
8) (integer) 0

TR.APPENDINTARRAY

类别 说明
语法 TR.APPENDINTARRAY <key> <value1> [<value2> <value3> ... <valueN>]
时间复杂度 O(C)
命令描述

将bitmap中指定bit位的值(value)设置为1,支持传入多个值。

选项
  • Key:Key名称(Tair Roaring数据结构)。
  • value:整形数字,表示待设置的bit位,取值范围为0 ~ 4294967296。
返回值
  • 执行成功:返回OK。
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.APPENDINTARRAY foo 9 10

返回示例:

OK

TR.DIFF

类别 说明
语法 TR.DIFF <destkey> <key1> <key2>
时间复杂度 O(C * M)
命令描述
计算key1与key2对应Roaring Bitmap的差集,并将结果储到destkey所指的键中。
说明 集群架构暂不支持该命令。

使用时请注意计算差集对象的运算顺序。例如,本例中是计算key1关于key2的差集。

选项
  • destkey:集合运算结果所存储的目标Key(Tair Roaring数据结构)。
  • Key:Key名称(Tair Roaring数据结构)。
返回值
  • 执行成功:返回OK。
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.DIFF result foo bar

返回示例:

OK

TR.SETFULL

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

创建一个新的Key,并使用1填充整个Roaring bitmap,bit位的长度为4294967296(最大值)。

选项
  • Key:Key名称(Tair Roaring数据结构)。
返回值
  • 执行成功:返回OK。
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.SETFULL foo

返回示例:

OK

TR.SETRANGE

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

将Roaring bitmap中start到end之间的bit位设置为1,区间左闭右开。

例如TR.SETRANGE foo 1 3,将创建foo为"011"。

选项
  • Key:Key名称(Tair Roaring数据结构)。
  • start:区间左端点。
  • end:区间右端点。
返回值
  • 执行成功:返回OK。
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.SETRANGE foo 2 7

返回示例:

OK

TR.OPTIMIZE

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

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

选项
  • Key:Key名称(Tair Roaring数据结构)。
返回值
  • 执行成功:返回OK。
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.OPTIMIZE foo

返回示例:

OK

TR.STAT

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

返回当前bitmap的统计信息, 包括各种容器的数量以及内存使用状况等信息。

选项
  • Key:Key名称(Tair Roaring数据结构)。
返回值
  • 执行成功能:返回Redis的统计信息(bulk string),说明如下。
        cardinality: 8                       #元素总数量
        number of containers: 1              #TairRoaring容器总数(RoaringBitmap概念)
        max value: 14                        #最大元素值
        min value: 0                         #最小元素值
        number of array containers: 1        #array容器个数(RoaringBitmap概念)
                array container values: 8
                array container bytes: 16
        number of bitset containers: 0       #bitset容器个数(RoaringBitmap概念)
                bitset container values: 0
                bitset container bytes: 0
        number of run containers: 0          #RLE容器个数(RoaringBitmap概念)
                run container values: 0
                run container bytes: 0
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.STAT bitmap_004

返回示例:

cardinality: 5
nnumber of containers: 1
nmax value: 6
nmin value: 2
nnumber of array containers: 0
    array container values: 0
    array container bytes: 0
number of bitset containers: 0
    bitset container values: 0
    bitset container bytes: 0
number of run containers: 1
    run container values: 5
    run container bytes: 6

TR.SETBITARRAY

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

根据传入的bit(由0和1组成的字符串),来创建一个位图(bitmap)。执行该命令时,Redis会逐个字符判断,只操作bit为1的字符,如果目标Key已存在则会覆盖已有数据。

选项
  • key:Key名称(Tair Roaring数据结构)。
  • value:由0和1构成的字符串,即需要设置的bit数组。
返回值
  • 执行成功:返回OK
  • 其它情况返回相应的异常信息。
示例

命令示例:

tr.setbitarray foo 10101001

返回示例:

OK 

TR.MIN

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

返回key对应的bitmap集合中首个bit值为1的偏移量,不存在时返回-1。

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

命令示例:

TR.MIN foo

返回示例:

4

TR.MAX

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

返回key对应的bitmap集合中bit值为1的最大偏移量,不存在时返回-1。

选项
  • Key:Key名称(Tair Roaring数据结构)。
返回值
  • 执行成功:
    • 返回bit值为1的最大偏移量,格式为Integer(整数)。
    • 返回-1,表示对应bitmap中不存在值为1的bit。
  • 其它情况返回相应的异常信息。
示例

命令示例:

TR.MAX foo

返回示例:

6