All Products
Search
Document Center

Tair:Roaring

Last Updated:Jun 27, 2024

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 takes advantage of the powerful computing performance and high stability provided by Tair to support business scenarios.

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

Important

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.

  1. On September 13, 2021, TairRoaring V1 was released for instances that run minor version 1.7.20 or later.

  2. 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 such as TR.SETBITS and TR.CLEARBITS, updates three commands with two of them still compatible with TairRoaring V1, and changes the name of one command.

  3. 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: TR.JACCARD, TR.CONTAINS, and TR.RANK. This version also changes the errors that are returned when specific commands are issued against a key that does not exist in the database. For example, the ERR key not found error message is removed.

Best practices

Select users by using TairRoaring

Prerequisites

A Tair DRAM-based instance that runs minor version 1.7.7 or later is created.

Note We recommend that you update your instance to the latest minor version for more features and higher stability. 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. For more information about cluster instances and read/write splitting instances, see Cluster architecture and Read/write splitting architecture.

Usage notes

The TairRoaring keys that you want to manage are stored on the Tair 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 set multiple bits to a value of 1.

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 set multiple bits to a value of 0.

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 that have been set to 1.

TR.APPENDBITARRAY

TR.APPENDBITARRAY key offset bitarray

Inserts a bit array into a position after 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

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 dataset and the operation is performed on the key.

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 set multiple bits to a value of 1.

Note

In TairRoaring V2, we recommend that you use TR.SETBITS instead of this command.

-

TR.SETINTARRAY

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

Creates a TairRoaring key based on the specified integer array. If the key already exists, this command overwrites the data in the key.

Note

In TairRoaring V2, we recommend that you use TR.SETBITS 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

In TairRoaring V2, we recommend that you use TR.APPENDBITARRAY 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 unavailable for keys that reside across slots in 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 unavailable for keys that reside across slots in cluster instances.

Added in V2.

TR.OPTIMIZE

TR.OPTIMIZE key

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

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 bits for value retrieval.

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. A value of 1 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 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 removed elements.

Added in V2.

TR.RANGE

TR.RANGE key start end

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.

TR.RANGEBITARRAY

TR.RANGEBITARRAY key start end

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.

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

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.

-

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.

TR.JACCARD

TR.JACCARD key1 key2

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.

TR.CONTAINS

TR.CONTAINS key1 key2

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.

TR.RANK

TR.RANK key offset

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

DEL

DEL key [key ...]

Deletes one or more TairRoaring keys.

-

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

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

  • Key: the key that you want to manage by running this command.

  • offset: the integer offset of the bit that you want to process. Valid values: 0 to 2^32.

  • value: the value that you want to set for the bit. The value can be set to 1 or 0.

Output

  • If the operation is successful, a bit value of 0 or 1 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.SETBIT foo 0 1

Sample output:

(integer) 0

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 set multiple bits to a value of 1.

Parameter

  • Key: the key that you want to manage by running this command.

  • offset: the integer offset of the bit that you want to process. Valid values: 0 to 2^32.

Output

  • If the operation is successful, the number of bits in the key that have a value of 1 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.SETBITS foo 9 10

Sample output:

(integer) 5

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 set multiple bits to a value of 0.

Parameter

  • Key: the key that you want to manage by running this command.

  • offset: the integer offset of the bit that you want to process. Valid values: 0 to 2^32.

Output

  • If the operation is successful, the number of bits in the key that have been set to 0 is returned.

  • If the key does not exist, a value of 0 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.CLEARBITS foo 9 10

Sample output:

(integer) 2

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 TR.SETRANGE foo 1 3 command, the system creates the 0111 foo key.

Parameter

  • Key: the key that you want to manage by running this command.

  • start: the start value of the interval. Valid values: 0 to 2^32.

  • end: the end value of the interval. Valid values: 0 to 2^32.

Output

  • If the operation is successful, the number of bits in the key that have been set to 1 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.SETRANGE foo 1 3

Sample output:

(integer) 3

TR.APPENDBITARRAY

Item

Description

Syntax

TR.APPENDBITARRAY key offset bitarray

Time complexity

O(C)

Command description

Inserts a bit array into a position after the specified bit in a TairRoaring key and overwrites the original data. The bit array consists of 0 and 1.

Parameter

  • Key: the key that you want to manage by running this command.

  • offset: the offset of the specified bit. Valid values: -1 to 2^32.

  • bitarray: the bit array that you want to insert. The bit array consists of 0 and 1 and overwrites the original data. Valid values: 0 to 2^32.

    Note

    The offset and bit array that you specify cannot have a combined length longer than 2^32. Otherwise, the operation cannot be performed.

Output

  • If the operation is successful, the number of bits in the key that have been set to 1 is returned.

  • Otherwise, an error message is returned.

Example

The TR.SETBITS foo 0 command is run in advance.

Sample command:

TR.APPENDBITARRAY foo 1 1101

Sample output:

(integer) 4

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

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 dataset and the operation is performed on the key.

Parameter

  • Key: the key that you want to manage by running this command.

  • start: the start value of the interval. Valid values: 0 to 2^32.

  • end: the end value of the interval. Valid values: 0 to 2^32.

Output

  • If the operation is successful, the number of bits in the key that have been set to 1 is returned.

  • If the key does not exist, the key is created as an empty dataset and the operation is performed on the key. If the operation is successful, the number of bits in the key that have been set to 1 is returned.

  • Otherwise, an error message is returned.

Example

The TR.SETBITS foo 0 2 3 5 command is run in advance.

Sample command:

TR.FLIPRANGE foo 0 5

Sample output:

(integer) 2

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 set multiple bits to a value of 1.

Note

In TairRoaring V2, we recommend that you use TR.SETBITS instead of this command.

Parameter

  • Key: the key that you want to manage by running this command.

  • value: the integer offset of the bit that you want to process. Valid values: 0 to 4294967296.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.APPENDINTARRAY foo 9 10

Sample output:

OK

TR.SETINTARRAY

Item

Description

Syntax

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

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

In TairRoaring V2, we recommend that you use TR.SETBITS instead of this command.

Parameter

  • Key: the key that you want to manage by running this command.

  • value: the integer offset of the bit that you want to process.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.SETINTARRAY foo 2 4 5 6

Sample output:

OK

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

In TairRoaring V2, we recommend that you use TR.APPENDBITARRAY instead of this command.

Parameter

  • key: the key that you want to manage by running this command.

  • value: the bit array string that consists of 0 and 1.

Output

  • If the operation is successful, OK is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

tr.setbitarray foo 10101001

Sample output:

OK 

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 unavailable for keys that reside across slots in cluster instances.

Parameter

  • destkey: the destination key that stores the result.

  • operation: the type of the bitwise operation. Valid values: AND, OR, XOR, NOT, and DIFF.

    Note
    • NOT operations can be performed only on one key.

    • DIFF operations calculate the difference between two keys only. Take note of the order of operations for calculating the difference. For example, the TR.BITOP result DIFF key1 key2 command subtracts the key2 value from the key1 value.

  • key: the key that you want to manage by running this command. Multiple keys can be specified.

Output

  • If the operation is successful, the integer number of bits in the result that have a value of 1 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.BITOP result OR foo bar

Sample output:

(integer) 6

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 unavailable for keys that reside across slots in cluster instances.

Parameter

  • operation: the type of the bitwise operation. Valid values: AND, OR, XOR, NOT, and DIFF.

    Note
    • NOT operations can be performed only on one key.

    • DIFF operations calculate the difference between two keys only. Take note of the order of operations for calculating the difference. For example, the TR.BITOP result DIFF key1 key2 command subtracts the key2 value from the key1 value.

  • key: the key that you want to manage by running this command. Multiple keys can be specified.

Output

  • If the operation is successful, the integer number of bits in the result that have a value of 1 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.BITOPCARD NOT foo

Sample output:

(integer) 2

TR.OPTIMIZE

Item

Description

Syntax

TR.OPTIMIZE key

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

  • Key: the key that you want to manage by running this command.

Output

  • If the operation is successful, OK is returned.

  • If the key does not exist, nil is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.OPTIMIZE foo

Sample output:

OK

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

  • Key: the key that you want to manage by running this command.

  • offset: the offset of the bit whose value you want to retrieve.

Output

  • If the operation is successful, a value of 0 or 1 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.GETBIT foo 0

Sample output:

(integer) 1

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 bits for value retrieval.

Parameter

  • Key: the key that you want to manage by running this command.

  • offset: the offset of the bit whose value you want to retrieve.

Output

  • If the operation is successful, the bit value is returned.

  • If the key does not exist, an empty array is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.GETBITS foo 3 4 6 8

Sample output:

1) (integer) 1
2) (integer) 1
3) (integer) 1
4) (integer) 0

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

  • Key: the key that you want to manage by running this command.

  • start: the start value of the interval. Valid values: 0 to 2^32.

  • end: the end value of the interval. Valid values: 0 to 2^32.

Output

  • If the operation is successful, the integer number of bits that have a value of 1 within the specified range in the key is returned.

  • If the key does not exist, a value of 0 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.BITCOUNT foo 4 9

Sample output:

(integer) 3

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. A value of 1 indicates the first bit retrieved by using the left-right counting approach.

Parameter

  • Key: the key that you want to manage by running this command.

  • value: the value of the bit whose offset you want to retrieve. The bit value can be 0 or 1.

  • count: the ordinal number of the bit. A negative number indicates that the right-left counting approach is used.

Output

  • If the operation is successful, the offset of the bit that has a value of 1 or 0 is returned.

  • If the key does not exist, a value of -1 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.BITPOS foo 1 -1

Sample output:

(integer) 6

TR.SCAN

Item

Description

Syntax

TR.SCAN key start_offset [COUNT count]

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 removed elements.

Parameter

  • Key: the key that you want to manage by running this command.

  • start_offset: the offset of the bit. The bit that matches this offset is scanned.

  • COUNT: the number of bits that you want to query. Default value: 10.

Output

  • If the operation is successful, an array that contains two elements is returned:

    • The first element is the next start_offset value. If the key is scanned, a value of 0 is returned.

    • The second element is the next offset that you specify.

    Note

    If the key does not exist, an array that consists of 0 and empty elements is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.SCAN foo 0 COUNT 2

Sample output:

1) (integer) 3
2) 1) (integer) 0
   2) (integer) 2

TR.RANGE

Item

Description

Syntax

TR.RANGE key start end

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

  • Key: the key that you want to manage by running this command.

  • start: the start value of the interval.

  • end: the end value of the interval.

Output

  • If the operation is successful, the offsets of the bits that have a value of 1 are returned.

  • If the key does not exist, an empty array is returned.

  • Otherwise, an error message is returned.

Example

The TR.SETBITS foo 0 2 3 5 command is run in advance.

Sample command:

TR.RANGE foo 0 5

Sample output:

1) (integer) 0
2) (integer) 2
3) (integer) 3
4) (integer) 5

TR.RANGEBITARRAY

Item

Description

Syntax

TR.RANGEBITARRAY key start end

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

  • Key: the key that you want to manage by running this command.

  • start: the start value of the interval.

  • end: the end value of the interval.

Output

  • If the operation is successful, the offsets of the bits that have a value of 1 are returned.

  • If the key does not exist, nil is returned.

  • Otherwise, an error message is returned.

Example

The TR.SETBITS foo 0 2 3 5 command is run in advance.

Sample command:

TR.RANGEBITARRAY foo 0 5

Sample output:

"101101"

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

  • Key: the key that you want to manage by running this command.

Output

  • If the operation is successful, the return value varies based on whether bits that have a value of 1 exist or whether the key exists.

    • If bits that have a value of 1 exist in the key, the integer offset of the first bit that has a value of 1 is returned.

    • If no bits that have a value of 1 exist in the key or if the key does not exist, a value of -1 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.MIN foo

Sample output:

4

TR.MAX

Item

Description

Syntax

TR.MAX key

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

  • Key: the key that you want to manage by running this command.

Output

  • If the operation is successful, the return value varies based on whether bits that have a value of 1 exist or whether the key exists.

    • If bits that have a value of 1 exist in the key, the integer offset of the last bit that has a value of 1 is returned.

    • If no bits that have a value of 1 exist in the key or if the key does not exist, a value of -1 is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.MAX foo

Sample output:

6

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

  • Key: the key that you want to manage by running this command.

  • JSON: If this parameter is specified, the statistical information is returned in the JSON format.

Output

  • If the operation is successful, the following output is returned:

    "{\"cardinality\":3, # Total number of elements in the key
    "number_of_containers":1, # Total number of containers in the key
    "max_value":6, # Maximum element value in the key
    \"min_value\":3, # Minimum element value in the key
    \"sum_value\":13,
    \"array_container\" :{# Number of array containers in the key
        \"number_of_containers\":1,
        \"container_cardinality\":3,
        \"container_allocated_bytes\":6},
    \"bitset_container\" :{# Number of bitset containers in the key
        \"number_of_containers\":0,
        \"container_cardinality\":0,
        \"container_allocated_bytes\":0},
    \"run_container\" :{# Number of run containers in the key
        \"number_of_containers\":0,
        \"container_cardinality\":0,
        \"container_allocated_bytes\":0}}"
    
                                            
  • If the key does not exist, nil is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.STAT foo JSON

Sample output:

"{\"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

Item

Description

Syntax

TR.JACCARD key1 key2

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

  • Key: the key that you want to manage by running this command.

Output

  • If the operation is successful, a double-typed Jaccard similarity coefficient is returned.

  • Otherwise, an error message is returned.

Example

Sample command:

TR.JACCARD foo1 foo2

Sample output:

"0.20000000000000001"

TR.CONTAINS

Item

Description

Syntax

TR.CONTAINS key1 key2

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

  • Key: the key that you want to manage by running this command.

Output

  • If the operation is successful, the return value varies based on whether key2 contains key1.

    • If key2 contains key1, a value of 1 is returned.

    • If key2 does not contain key1, a value of 0 is returned.

  • Otherwise, an error message is returned.

Example

The TR.SETBITS fooM 1 2 3 10 and TR.SETBITS foom 1 2 commands are run in advance.

Sample command:

TR.CONTAINS foom fooM

Sample output:

(integer) 1

TR.RANK

Item

Description

Syntax

TR.RANK key offset

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

  • Key: the key that you want to manage by running this command.

  • offset: the offset of the specified bit. The value must be an integer.

Output

  • If the operation is successful, the number of bits that have a value of 1 is returned.

  • Otherwise, an error message is returned.

Example

The TR.SETBITS fooM 1 2 3 10 command is run in advance.

Sample command:

TR.RANK fooM 10

Sample output:

(integer) 4

Error messages

Error message

Description

WRONGTYPE Operation against a key holding the wrong kind of value

Incorrect key type: The key is not a TairRoaring key.

ERR bad arguments, must be unsigned 32-bit integer

Incorrect parameter type: The parameter values cannot be converted into 32-bit integers.

ERR invalid arguments, maybe out of range or illegal

Invalid parameters:

  • The offset is not a 32-bit integer.

  • The start and end offsets are invalid.

  • The parameter value exceeds the maximum number of elements allowed for a TairRoaring key.

ERR key already exist

The TairRoaring key already exists, and its data cannot be overwritten.

Note

This error is fixed in TairRoaring V2.2.

ERR key not found

The TairRoaring key does not exist.

Note

This error is fixed in TairRoaring V2.2.