云原生内存数据库Tair：TairRoaring

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

设置Roaring Bitmap中指定偏移量（offset）的bit值为1，支持传入多个值。

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

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

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

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

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

获取Roaring Bitmap中指定偏移量（offset）的bit值。

获取Roaring Bitmap中指定偏移量（offset）的bit值，支持查询多个值。

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

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

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

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

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

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

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

获取Roaring Bitmap中从offset为0到指定offset区间内（包含该值），bit值为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

设置Roaring Bitmap中指定偏移量（offset）的bit值为1，支持传入多个值。

• Key：Key名称（TairRoaring数据结构）。
• offset：整型数字，表示待设置bit的偏移量，取值范围为0 ~ 2^32。

• 执行成功：返回更新后Roaring Bitmap中bit值为1的数量。
• 其他情况返回相应的异常信息。

命令示例：

TR.SETBITS foo 9 10

返回示例：

(integer) 5

设置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

设置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

将由连续的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”。

对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”。

• Key：Key名称（TairRoaring数据结构）。
• value：整型数字，表示待设置的bit位，取值范围为0 ~ 4294967296。

• 执行成功：返回OK。
• 其他情况返回相应的异常信息。

命令示例：

TR.APPENDINTARRAY foo 9 10

返回示例：

OK

• Key：Key名称（TairRoaring数据结构）。
• value：整型数字，表示待设置的bit位。

• 执行成功：返回OK。
• 其他情况返回相应的异常信息。

命令示例：

TR.SETINTARRAY foo 2 4 5 6

返回示例：

OK

• key：Key名称（TairRoaring数据结构）。
• value：由0和1构成的字符串，即需要设置的bit数组。

• 执行成功：返回OK。
• 其他情况返回相应的异常信息。

命令示例：

tr.setbitarray foo 10101001

返回示例：

OK 

• 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

• 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

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

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

• 执行成功：返回OK。
• 若key不存在：返回nil。
• 其他情况返回相应的异常信息。

命令示例：

TR.OPTIMIZE foo

返回示例：

OK

获取Roaring Bitmap中指定偏移量（offset）的bit值。

• Key：Key名称（TairRoaring数据结构）。
• offset：待查询的偏移量。

• 执行成功：返回0或1，表示bit位的值。
• 其他情况返回相应的异常信息。

命令示例：

TR.GETBIT foo 0

返回示例：

(integer) 1

获取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

获取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

获取第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

• 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

获取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

获取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"

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

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

• 执行成功：
  • 返回首个bit值为1的偏移量，格式为Integer（整数）。
  • 返回-1，表示key不存在或者该Roaring Bitmap中不存在值为1的bit。
• 其他情况返回相应的异常信息。

命令示例：

TR.MIN foo

返回示例：

4

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

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

• 执行成功：
  • 返回最后一个bit值为1的偏移量，格式为Integer（整数）。
  • 返回-1，表示key不存在或者该Roaring Bitmap中不存在值为1的bit。
• 其他情况返回相应的异常信息。

命令示例：

TR.MAX foo

返回示例：

6

获取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}}"

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

• 执行成功：返回Jaccard相似系数（Double类型）。
• 其他情况返回相应的异常信息。

命令示例：

TR.JACCARD foo1 foo2

返回示例：

"0.20000000000000001"

• 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

获取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

• 非32-bit整型的offset不符合规则。
• 参数的[start,end]不符合规则。
• 参数超过Roaring Bitmap的元素个数。