云数据库 Tair（兼容 Redis®）：Roaring

类型

命令

语法

说明

版本变更

写操作

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]

-

TR.SETINTARRAY

TR.SETINTARRAY key value [value1 value2 ... valueN]

-

TR.SETBITARRAY

TR.SETBITARRAY key value

-

TR.BITOP

TR.BITOP destkey operation key [key1 key2 ... keyN]

-

TR.BITOPCARD

TR.BITOPCARD operation key [key1 key2 ... keyN]

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]

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

V2.2新增

TR.CONTAINS

TR.CONTAINS key1 key2

V2.2新增

TR.RANK

TR.RANK key offset

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

V2.2新增

通用

DEL

DEL key [key ...]

使用原生Redis的DEL命令可以删除一条或多条TairRoaring数据。

-

类别

说明

语法

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 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 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 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 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 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 key value [value1 value2 ... valueN]

时间复杂度

O(C)

命令描述

选项

• Key：Key名称（TairRoaring数据结构）。

• value：整型数字，表示待设置的bit位，取值范围为0 ~ 4294967296。

返回值

• 执行成功：返回OK。

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

示例

命令示例：

TR.APPENDINTARRAY foo 9 10

返回示例：

OK

类别

说明

语法

TR.SETINTARRAY key value [value1 value2 ... valueN]

时间复杂度

O(C)

命令描述

选项

• Key：Key名称（TairRoaring数据结构）。

• value：整型数字，表示待设置的bit位。

返回值

• 执行成功：返回OK。

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

示例

命令示例：

TR.SETINTARRAY foo 2 4 5 6

返回示例：

OK

类别

说明

语法

TR.SETBITARRAY key value

时间复杂度

O(C)

命令描述

选项

• key：Key名称（TairRoaring数据结构）。

• value：由0和1构成的字符串，即需要设置的bit数组。

返回值

• 执行成功：返回OK。

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

示例

命令示例：

tr.setbitarray foo 10101001

返回示例：

OK 

类别

说明

语法

TR.BITOP destkey operation key [key1 key2 ... keyN]

时间复杂度

O(C * M)

命令描述

选项

• 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 operation key [key1 key2 ... keyN]

时间复杂度

O(C * M)

命令描述

选项

• 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 key

时间复杂度

O(M)

命令描述

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

选项

• Key：Key名称（TairRoaring数据结构）。

返回值

• 执行成功：返回OK。

• 若key不存在：返回nil。

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

示例

命令示例：

TR.OPTIMIZE foo

返回示例：

OK

类别

说明

语法

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 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 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 <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 key start_offset [COUNT count]

时间复杂度

O(C)

命令描述

选项

• 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 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 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 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 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 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 key1 key2

时间复杂度

O(M)

命令描述

选项

• Key：Key名称（TairRoaring数据结构）。

返回值

• 执行成功：返回Jaccard相似系数（Double类型）。

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

示例

命令示例：

TR.JACCARD foo1 foo2

返回示例：

"0.20000000000000001"

类别

说明

语法

TR.CONTAINS key1 key2

时间复杂度

O(M)

命令描述

选项

• Key：Key名称（TairRoaring数据结构）。

返回值

• 执行成功：

  • 返回1，表示key2包含key1，即key1是key2的子集。

  • 返回0，表示key2不包含key1，即key1不是key2的子集。

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

示例

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

命令示例：

TR.CONTAINS foom fooM

返回示例：

(integer) 1

类别

说明

语法

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对象已存在，且不支持覆盖。

ERR key not found

Roaring Bitmap对象不存在, 不支持操作。