The TairRoaring data structure is a Tair-based Roaring bitmap implementation. This topic introduces TairRoaring and its supported commands.
Overview
Bitmap (also known as bitset) is a common data structure that uses small amounts of storage to optimize queries of large amounts of data. Bitmaps save more space than hash-based implementations but are unsuitable for storing sparse data. Compressed bitmaps were developed in response to this issue. Roaring bitmaps are a more efficient and balanced type of compressed bitmaps recognized by the industry.
- TairRoarings can strike a balance between performance and space complexity by means of two-level indexes and dynamic containers.
- TairRoarings use optimization techniques such as single instruction, multiple data (SIMD), vectorization, and popcount algorithms to improve computing efficiency and deliver efficient time and space complexity.
- TairRoarings provide powerful computing performance and high stability for a variety of business scenarios based on ApsaraDB for Redis Enhanced Edition (Tair).
TairRoarings are suitable for use in industries such as live streaming, music, and e-commerce. You can use TairRoarings to add multidimensional tags to users for scenarios such as personalized recommendation and precision marketing.
Release notes- TR.RANGEINTARRAY: TR.RANGEINTARRAY in TairRoaring V1 is changed to TR.RANGE in TairRoaring V2.
- TR.SETRANGE: The output of TR.SETRANGE is changed from
OK
in TairRoaring V1 to the number of bits set to 1 in TairRoaring V2.
- On Sep 13, 2021, TairRoaring V1 was released.
- On March 11, 2022, TairRoaring V2 was released. We recommend that you update the minor version of your instance to 1.7.27 or later.
For more information, see Update the minor version.
TairRoaring V2 optimizes some command implementations and improves command performance. TairRoaring V2 comes with eight new commands including TR.SETBITS and TR.CLEARBITS, updates three commands with two of them still compatible with TairRoaring V1, and changes the name of one command. For more information, see Supported commands.
Best practices
Select users by using TairRoaringPrerequisites
- The instance is a performance-enhanced instance of the ApsaraDB for Redis Enhanced Edition (Tair). For more information, see Performance-enhanced instances.
- The instance is updated to the latest minor version. For more information, see Update the minor version.
Note If your instance is a cluster instance or read/write splitting instance, the proxy nodes in your instance must also be of the latest minor version to ensure that all commands can be run as expected. For more information about cluster instances and read/write splitting instances, see Cluster master-replica instances and Read/write splitting instances.
Precautions
The TairRoarings that you want to manage are stored in the performance-enhanced instance.
Supported commands
Type | Command | Syntax | Description | Version change |
---|---|---|---|---|
Write operation | TR.SETBIT | TR.SETBIT key offset value |
Sets the specified bit in a TairRoaring key to a value of 1 or 0 and returns the original bit value. The offset starts from 0. |
- (N/A) |
TR.SETBITS | TR.SETBITS key offset [offset1 offset2 ... offsetN] |
Sets the value of the specified bit in a TairRoaring key to 1. You can specify multiple bit values. |
Added in V2. | |
TR.CLEARBITS | TR.CLEARBITS key offset [offset1 offset2 ... offsetN] |
Sets the value of the specified bit in a TairRoaring key to 0. If the specified bit already has a value of 0, the operation is not performed. You can specify multiple bit values. |
Added in V2. | |
TR.SETRANGE | TR.SETRANGE key start end |
Sets the bits within the specified range in a TairRoaring key to a value of 1. The range is a closed interval. |
Updated in V2. After the command update in V2, the command output is changed to the number of bits set to 1. | |
TR.APPENDBITARRAY | TR.APPENDBITARRAY key offset bitarray |
Inserts a bit array into a position right behind the specified bit in a TairRoaring key and overwrites the original data. The bit array consists of 0 and 1. |
Added in V2. | |
TR.FLIPRANGE | TR.FLIPRANGE key start end |
Switches the values for bits within the specified range in a TairRoaring key from 0 to 1 or from 1 to 0. The range is a closed interval. |
Added in V2. | |
TR.APPENDINTARRAY | TR.APPENDINTARRAY key value [value1 value2 ... valueN] |
Sets the value of the specified bit in a TairRoaring key to 1. You can specify multiple
bit values.
Note We recommend that you use TR.SETBITS in TairRoaring V2 instead of this command.
|
- | |
TR.SETINTARRAY | TR.SETINTARRAY key value [value1 value2 ... valueN] |
Creates a TairRoaring key from an integer array. If the key already exists, this command
overwrites the data in the key.
Note We recommend that you use TR.SETBITS in TairRoaring V2 instead of this command.
|
- | |
TR.SETBITARRAY | TR.SETBITARRAY key value |
Creates a TairRoaring key based on the specified bit array string. The bit array string
consists of 0 and 1. If the key already exists, this command overwrites the data in
the key.
Note We recommend that you use TR.APPENDBITARRAY in TairRoaring V2 instead of this command.
|
- | |
TR.BITOP | TR.BITOP destkey operation key [key1 key2 ... keyN] |
Performs a bitwise operation on multiple TairRoaring keys and stores the result in
the destination key. The AND, OR, XOR, NOT, and DIFF bitwise operations are supported.
Note This command is not supported by cluster instances.
|
- | |
TR.BITOPCARD | TR.BITOPCARD operation key [key1 key2 ... keyN] |
Performs a bitwise operation on multiple TairRoaring keys. The AND, OR, XOR, NOT, and DIFF bitwise operations are supported.
Note This command is not supported by cluster instances.
|
Added in V2. | |
TR.DIFF | TR.DIFF destkey key1 key2 |
Calculates the difference between the key1 value and the key2 value and stores the result in the destination key. Note
|
- | |
TR.OPTIMIZE | TR.OPTIMIZE key |
Optimizes the storage of a TairRoaring key. If the key is relatively large and is used mainly for read operations after the key is created, you can run this command. |
- | |
Read operation | TR.GETBIT | TR.GETBIT key offset |
Retrieves the value of the specified bit from a TairRoaring key. |
- |
TR.GETBITS | TR.GETBITS key offset [offset1 offset2 ... offsetN] |
Retrieves the value of the specified bit from a TairRoaring key. You can specify multiple bit values. |
Added in V2. | |
TR.BITCOUNT | TR.BITCOUNT key [start end] |
Counts the number of bits that have a value of 1 within the specified range in a TairRoaring key. The range is a closed interval. |
Updated in V2 and compatible with V1. | |
TR.BITPOS | TR.BITPOS <key> <value> [count] |
Retrieves the offset of the bit that has an ordinal number of count. A bit can have a value of 1 or 0. The count parameter is optional and has a default value of 1, which indicates the first bit retrieved by using the left-right counting approach. |
Updated in V2 and compatible with V1. | |
TR.SCAN | TR.SCAN key start_offset [COUNT count] |
Scans the bits located behind the specified bit in a TairRoaring key and returns the
offsets corresponding to the scanned bits that have a value of 1. The returned cursor
is the offset corresponding to the key.
Note This command may or may not scan and return added or deleted elements.
|
Added in V2. | |
TR.RANGE | TR.RANGE key start end |
Returns the offsets of the bits that have a value of 1 within the specified range in a TairRoaring key. The range is a closed interval. |
Renamed as TR.RANGE in V2 from TR.RANGEINTARRAY in V1. | |
TR.MIN | TR.MIN key |
Retrieves the offset of the first bit that has a value of 1 in a TairRoaring key. If no bits have a value of 1, a value of -1 is returned. |
- | |
TR.MAX | TR.MAX key |
Returns the offset of the last bit that has a value of 1 in a TairRoaring key. If no bits have a value of 1, -1 is returned. |
- | |
TR.STAT | TR.STAT key [JSON] |
Returns the statistical information of the specified TairRoaring key. The information includes the number of containers and the memory usage. |
Added in V2. | |
General-purpose operation | DEL | DEL key [key ...] |
Deletes one or more TairRoaring keys. | - |
- The following section describes the command syntax:
Uppercase keyword
: the command keyword.Italic
: Words in italic indicate variable information that you supply.[options]
: optional parameters. Parameters that are not included in brackets are required.A|B
: specifies that these parameters are mutually exclusive. Select one of two or more parameters....
: specifies to repeat the preceding content.
-
In this topic, the letters used in time complexity expressions Time complexity indicate topic-specific meanings:
- C indicates the argc or range of parameters.
- M indicates the number of bits set to 1 in a data structure, such as the number of nodes in a list or the number of fields in a hash.
TR.SETBIT
Item | Description |
---|---|
Syntax | TR.SETBIT key offset value |
Time complexity | O(1) |
Command description |
Sets the specified bit in a TairRoaring key to a value of 1 or 0 and returns the original bit value. The offset starts from 0. |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.SETBITS
Item | Description |
---|---|
Syntax | TR.SETBITS key offset [offset1 offset2 ... offsetN] |
Time complexity | O(C) |
Command description |
Sets the value of the specified bit in a TairRoaring key to 1. You can specify multiple bit values. |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.CLEARBITS
Item | Description |
---|---|
Syntax | TR.CLEARBITS key offset [offset1 offset2 ... offsetN] |
Time complexity | O(C) |
Command description |
Sets the value of the specified bit in a TairRoaring key to 0. If the specified bit already has a value of 0, the operation is not performed. You can specify multiple bit values. |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.SETRANGE
Item | Description |
---|---|
Syntax | TR.SETRANGE key start end |
Time complexity | O(C) |
Command description |
Sets the bits within the specified range in a TairRoaring key to a value of 1. The range is a closed interval. For example, if you run the |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.APPENDBITARRAY
Item | Description |
---|---|
Syntax | TR.APPENDBITARRAY key offset bitarray |
Time complexity | O(C) |
Command description |
Inserts a bit array into a position right behind the specified bit in a TairRoaring key and overwrites the original data. The bit array consists of 0 and 1. |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
In this case, the TairRoaring foo key is ”101101“. |
TR.FLIPRANGE
Item | Description |
---|---|
Syntax | TR.FLIPRANGE key start end |
Time complexity | O(C) |
Command description |
Switches the values for bits within the specified range in a TairRoaring key from 0 to 1 or from 1 to 0. The range is a closed interval. |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
In this case, the TairRoaring foo key is "01001". |
TR.APPENDINTARRAY
Item | Description |
---|---|
Syntax | TR.APPENDINTARRAY key value [value1 value2 ... valueN] |
Time complexity | O(C) |
Command description |
Sets the value of the specified bit in a TairRoaring key to 1. You can specify multiple
bit values.
Note We recommend that you use TR.SETBITS in TairRoaring V2 instead of this command.
|
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.SETINTARRAY
Item | Description |
---|---|
Syntax | TR.SETINTARRAY key value [value1 value2 ... valueN] |
Time complexity | O(C) |
Command description |
Creates a TairRoaring key from an integer array. If the key already exists, this command
overwrites the data in the key.
Note We recommend that you use TR.SETBITS in TairRoaring V2 instead of this command.
|
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.SETBITARRAY
Item | Description |
---|---|
Syntax | TR.SETBITARRAY key value |
Time complexity | O(C) |
Command description |
Creates a TairRoaring key based on the specified bit array string. The bit array string
consists of 0 and 1. If the key already exists, this command overwrites the data in
the key.
Note We recommend that you use TR.APPENDBITARRAY in TairRoaring V2 instead of this command.
|
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.BITOP
Item | Description |
---|---|
Syntax | TR.BITOP destkey operation key [key1 key2 ... keyN] |
Time complexity | O(C * M) |
Command description |
Performs a bitwise operation on multiple TairRoaring keys and stores the result in
the destination key. The AND, OR, XOR, NOT, and DIFF bitwise operations are supported.
Note This command is not supported by cluster instances.
|
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.BITOPCARD
Item | Description |
---|---|
Syntax | TR.BITOPCARD operation key [key1 key2 ... keyN] |
Time complexity | O(C * M) |
Command description |
Performs a bitwise operation on multiple TairRoaring keys. The AND, OR, XOR, NOT, and DIFF bitwise operations are supported.
Note This command is not supported by cluster instances.
|
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.DIFF
Item | Description |
---|---|
Syntax | TR.DIFF destkey key1 key2 |
Time complexity | O(C * M) |
Command description |
Calculates the difference between the key1 value and the key2 value and stores the result in the destination key. Note
When you use this command, take note of the order of operations for calculating the difference. In this example, the difference is calculated by subtracting the key2 value from the key1 value. |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.OPTIMIZE
Item | Description |
---|---|
Syntax | TR.OPTIMIZE key |
Time complexity | O(M) |
Command description |
Optimizes the storage of a TairRoaring key. If the key is relatively large and is used mainly for read operations after the key is created, you can run this command. |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.GETBIT
Item | Description |
---|---|
Syntax | TR.GETBIT key offset |
Time complexity | O(1) |
Command description |
Retrieves the value of the specified bit from a TairRoaring key. |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.GETBITS
Item | Description |
---|---|
Syntax | TR.GETBITS key offset [offset1 offset2 ... offsetN] |
Time complexity | O(C) |
Command description |
Retrieves the value of the specified bit from a TairRoaring key. You can specify multiple bit values. |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.BITCOUNT
Item | Description |
---|---|
Syntax | TR.BITCOUNT key [start end] |
Time complexity | O(M) |
Command description |
Counts the number of bits that have a value of 1 within the specified range in a TairRoaring key. The range is a closed interval. |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.BITPOS
Item | Description |
---|---|
Syntax | TR.BITPOS <key> <value> [count] |
Time complexity | O(C) |
Command description |
Retrieves the offset of the bit that has an ordinal number of count. A bit can have a value of 1 or 0. The count parameter is optional and has a default value of 1, which indicates the first bit retrieved by using the left-right counting approach. |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.SCAN
Item | Description |
---|---|
Syntax | TR.SCAN key start_offset [COUNT count] |
Time complexity | O(C) |
Command description |
Scans the bits located behind the specified bit in a TairRoaring key and returns the
offsets corresponding to the scanned bits that have a value of 1. The returned cursor
is the offset corresponding to the key.
Note This command may or may not scan and return added or deleted elements.
|
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.RANGE
Item | Description |
---|---|
Syntax | TR.RANGE key start end |
Time complexity | O(C) |
Command description |
Returns the offsets of the bits that have a value of 1 within the specified range in a TairRoaring key. The range is a closed interval. |
Parameter |
|
Output |
|
Example |
The Sample command:
Sample output:
|
TR.MIN
Item | Description |
---|---|
Syntax | TR.MIN key |
Time complexity | O(1) |
Command description |
Retrieves the offset of the first bit that has a value of 1 in a TairRoaring key. If no bits have a value of 1, a value of -1 is returned. |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.MAX
Item | Description |
---|---|
Syntax | TR.MAX key |
Time complexity | O(1) |
Command description |
Returns the offset of the last bit that has a value of 1 in a TairRoaring key. If no bits have a value of 1, -1 is returned. |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
TR.STAT
Item | Description |
---|---|
Syntax | TR.STAT key [JSON] |
Time complexity | O(M) |
Command description |
Returns the statistical information of the specified TairRoaring key. The information includes the number of containers and the memory usage. |
Parameter |
|
Output |
|
Example |
Sample command:
Sample output:
|
Error messages
Error message | Description |
---|---|
WRONGTYPE Operation against a key holding the wrong kind of value |
The key type is incorrect: The key is not a TairRoaring key. |
ERR bad arguments, must be unsigned 32-bit integer |
The parameter type is incorrect: The parameter values cannot be converted into 32-bit integers. |
ERR invalid arguments, maybe out of range or illegal |
The parameters are invalid:
|
ERR key already exist |
The TairRoaring key already exists, and its data cannot be overwritten. |
ERR key not found |
The TairRoaring key does not exist. |