TairRoaring is a Tair-based data structure for Roaring bitmaps. This topic describes 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 an industry-recognized bitmap type that is more efficient and balanced than other compressed bitmaps.
Roaring bitmaps are optimized in TairRoaring in the following ways:
TairRoaring can strike a balance between performance and space complexity in a large number of scenarios by using two-level indexes and dynamic containers.
TairRoaring uses optimization techniques such as single instruction, multiple data (SIMD), vectorization, and popcount algorithms to improve computing efficiency and deliver efficient time and space complexity.
TairRoaring provides powerful computing performance and high stability to support business scenarios based on Tair.
Typical scenarios
TairRoaring is suitable for use in industries such as livestreaming, music, and e-commerce. You can use TairRoaring to add multidimensional tags to users for scenarios such as personalized recommendations and precision marketing.
Release notes
Changes in TairRoaring V2:
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 that have been set to 1 in TairRoaring V2.
On September 13, 2021, TairRoaring V1 was released for instances that run minor version 1.7.20 or later.
On March 11, 2022, TairRoaring V2 was released for instances that run minor version 1.7.27 or later.
TairRoaring V2 optimizes specific command implementations to improve performance. TairRoaring V2 comes with nine 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.
On April 20, 2022, TairRoaring V2.2 was released for instances that run minor version 1.8.1 or later
TairRoaring V2.2 comes with three new commands, which are TR.JACCARD, TR.CONTAINS, and TR.RANK, and updates specific command outputs. For example, the
ERR key not found
error message is removed if the specified key does not exist.
Best practices
Select users by using TairRoaring
Prerequisites
A Tair DRAM-based instance that runs minor version 1.7.7 or later is created.
The latest minor version provides more features and higher stability. We recommend that you update the instance to the latest minor version. For more information, see Update the minor version of an instance. If your instance is a cluster instance or read/write splitting instance, we recommend that you update the proxy nodes in the instance to the latest minor version to ensure that all commands can be run as expected.
Usage notes
The TairRoarings that you want to manage are stored on the Tair instance.
Supported commands
Type | Command | Syntax | Description | Version change |
Write operation |
| 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) | |
| Sets the value of the specified bit in a TairRoaring key to 1. You can set multiple bits to a value of 1. | Added in V2. | ||
| 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 set multiple bits to a value of 0. | Added in V2. | ||
| 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 that have been set to 1. | ||
| 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. | ||
| Changes 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. If the key does not exist, the key is created as an empty data set and the operation is performed on the key. | Added in V2. | ||
| Sets the value of the specified bit in a TairRoaring key to 1. You can set multiple bits to a value of 1. Note We recommend that you use TR.SETBITS in TairRoaring V2 instead of this command. | - | ||
| Creates a TairRoaring key based on the specified 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. | - | ||
| 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. | - | ||
| 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 unavailable for keys that reside across slots in cluster instances. | - | ||
| Performs a bitwise operation on multiple TairRoaring keys. The AND, OR, XOR, NOT, and DIFF bitwise operations are supported. Note This command is unavailable for keys that reside across slots in cluster instances. | Added in V2. | ||
| Optimizes the storage of a TairRoaring key. If the key stores a large number of elements and is used mainly for read operations after the key is created, you can run this command. | - | ||
Read operation |
| Retrieves the value of the specified bit from a TairRoaring key. | - | |
| Retrieves the value of the specified bit from a TairRoaring key. You can specify multiple bits for value retrieval. | Added in V2. | ||
| 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. | ||
| 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. A value of 1 indicates the first bit retrieved by using the left-right counting approach. | Updated in V2 and compatible with V1. | ||
| Scans all bits located after a specified bit in a TairRoaring key and returns the offsets corresponding to a count of 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. | ||
| Retrieves 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. | ||
| Retrieves a string that consists of bit values of 0 and 1 within the specified range in a TairRoaring key. The range is a closed interval. | Added in V2. | ||
| 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. | - | ||
| Retrieves 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. | - | ||
| Returns the statistical information of the specified TairRoaring key. The information includes the number of containers and the memory usage. | Added in V2. | ||
| Retrieves the Jaccard similarity coefficient of two TairRoaring keys. The higher the coefficient, the higher the similarity. Note This command is unavailable for keys that reside across slots in cluster instances. | Added in V2.2. | ||
| Checks whether key2 contains key1. If yes, key1 is a subset of key2 and a value of 1 is returned. Otherwise, key1 is not a subset of key2 and a value of 0 is returned. Note This command is unavailable for keys that reside across slots in cluster instances. | Added in V2.2. | ||
| Retrieves the number of bits that have a value of 1 within the range from the first bit to the specified bit. The range is a closed interval. | Added in V2.2. | ||
General-purpose operation |
| Deletes one or more TairRoaring keys. | - |
The following section describes the command syntax:
Uppercase keyword
: indicates the command keyword.Italic text
: indicates variables.[options]
: indicates that the enclosed parameters are optional. Parameters that are not enclosed by brackets must be specified.A|B
: indicates that the parameters separated by the vertical bars (|) are mutually exclusive. Only one of the parameters can be specified....
: indicates that the parameter preceding this symbol can be repeatedly specified.
In this topic, the letters used in time complexity expressions 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 |
|
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 |
|
Time complexity | O(C) |
Command description | Sets the value of the specified bit in a TairRoaring key to 1. You can set multiple bits to a value of 1. |
Parameter |
|
Output |
|
Example | Sample command:
Sample output:
|
TR.CLEARBITS
Item | Description |
Syntax |
|
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 set multiple bits to a value of 0. |
Parameter |
|
Output |
|
Example | Sample command:
Sample output:
|
TR.SETRANGE
Item | Description |
Syntax |
|
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 |
|
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 |
|
Time complexity | O(C) |
Command description | Changes 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. If the key does not exist, the key is created as an empty data set and the operation is performed on the key. |
Parameter |
|
Output |
|
Example | The Sample command:
Sample output:
In this case, the TairRoaring foo key is "01001". |
TR.APPENDINTARRAY
Item | Description |
Syntax |
|
Time complexity | O(C) |
Command description | Sets the value of the specified bit in a TairRoaring key to 1. You can set multiple bits to a value of 1. 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 |
|
Time complexity | O(C) |
Command description | Creates a TairRoaring key based on the specified 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 |
|
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 |
|
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 unavailable for keys that reside across slots in cluster instances. |
Parameter |
|
Output |
|
Example | Sample command:
Sample output:
|
TR.BITOPCARD
Item | Description |
Syntax |
|
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 unavailable for keys that reside across slots in cluster instances. |
Parameter |
|
Output |
|
Example | Sample command:
Sample output:
|
TR.OPTIMIZE
Item | Description |
Syntax |
|
Time complexity | O(M) |
Command description | Optimizes the storage of a TairRoaring key. If the key stores a large number of elements 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 |
|
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 |
|
Time complexity | O(C) |
Command description | Retrieves the value of the specified bit from a TairRoaring key. You can specify multiple bits for value retrieval. |
Parameter |
|
Output |
|
Example | Sample command:
Sample output:
|
TR.BITCOUNT
Item | Description |
Syntax |
|
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 |
|
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. A value of 1 indicates the first bit retrieved by using the left-right counting approach. |
Parameter |
|
Output |
|
Example | Sample command:
Sample output:
|
TR.SCAN
Item | Description |
Syntax |
|
Time complexity | O(C) |
Command description | Scans all bits located after a specified bit in a TairRoaring key and returns the offsets corresponding to a count of 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 |
|
Time complexity | O(C) |
Command description | Retrieves 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.RANGEBITARRAY
Item | Description |
Syntax |
|
Time complexity | O(C) |
Command description | Retrieves a string that consists of bit values of 0 and 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 |
|
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 |
|
Time complexity | O(1) |
Command description | Retrieves 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 |
|
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:
|
TR.JACCARD
Item | Description |
Syntax |
|
Time complexity | O(M) |
Command description | Retrieves the Jaccard similarity coefficient of two TairRoaring keys. The higher the coefficient, the higher the similarity. Note This command is unavailable for keys that reside across slots in cluster instances. |
Parameter |
|
Output |
|
Example | Sample command:
Sample output:
|
TR.CONTAINS
Item | Description |
Syntax |
|
Time complexity | O(M) |
Command description | Checks whether key2 contains key1. If yes, key1 is a subset of key2 and a value of 1 is returned. Otherwise, key1 is not a subset of key2 and a value of 0 is returned. Note This command is unavailable for keys that reside across slots in cluster instances. |
Parameter |
|
Output |
|
Example | The Sample command:
Sample output:
|
TR.RANK
Item | Description |
Syntax |
|
Time complexity | O(M) |
Command description | Retrieves the number of bits that have a value of 1 within the range from the first bit to the specified bit. The range is a closed interval. |
Parameter |
|
Output |
|
Example | The Sample command:
Sample output:
|
Error messages
Error message | Description |
| The key type is incorrect: The key is not a TairRoaring key. |
| The parameter type is incorrect: The parameter values cannot be converted into 32-bit integers. |
| The parameters are invalid:
|
| The TairRoaring key already exists, and its data cannot be overwritten. Note This error is fixed in TairRoaring V2.2. |
| The TairRoaring key does not exist. Note This error is fixed in TairRoaring V2.2. |