全部產品
Search

搜尋本產品

    ：Roaring

    文件中心

    ：Roaring

    更新時間：Sep 25, 2024

    TairRoaring是基於Tair引擎的Roaring Bitmap實現，本文介紹TairRoaring及其支援的命令。

    TairRoaring簡介

    Bitmap（又名Bitset）是一種常用的資料結構，使用少量的儲存空間來實現海量資料的查詢最佳化。儘管Bitmap相比常規基於Hash結構的實現節省了大量記憶體空間，但是常規Bitmap對於稀疏情境下的資料存放區仍不夠友好，因此有了各種壓縮Bitmap的實現（Compressed bitmap），Roaring Bitmap就是業界公認的一種更高效和均衡的Bitmap壓縮儲存的實現。

    TairRoaring在此基礎上完成大量最佳化：

    • 通過2層索引和多種動態容器（Container），平衡了多種情境下效能和空間效率。

    • 使用了包括SIMD instructions、Vectorization、PopCnt演算法等多種工程最佳化，提升了計算效率，實現了高效的時空效率。

    • 基於Tair提供的強大計算效能和極高的穩定性，為使用者情境保駕護航。

    典型情境

    適用於直播、音樂、電商等行業，通過使用者多維度標籤，進行個人化推薦、精準營銷等情境。

    發布記錄

    重要

    V2版本Breaking Change公告：

    • TR.RANGEINTARRAY：V1版本的TR.RANGEINTARRAY命令名稱修改為V2版本的TR.RANGE，其內容無變化。

    • TR.SETRANGE：V1版本的TR.SETRANGE命令的傳回值為OK，V2版本傳回值為成功設定bit值為1的數量，其他內容無變化。

    1. 2021年9月13日發布TairRoaring V1版本，請將小版本升級至1.7.20及以上。

    2. 2022年3月11日發布TairRoaring V2版本，請將小版本升級至1.7.27及以上。

      該版本最佳化了部分命令的實現，提升了效能。新增TR.SETBITS、TR.CLEARBITS等9個命令，向前相容擴充2個命令，更新1個命令，更名1個命令。

    3. 2022年4月20日發布TairRoaring V2.2版本，請將小版本升級至1.8.1及以上。

      該版本新增TR.JACCARD、TR.CONTAINS、TR.RANK命令，更新部分命令在key不存在時的返回錯誤（移除了ERR key not found）。

    最佳實務

    基於TairRoaring實現人群圈選方案

    前提條件

    執行個體為Tair記憶體型，且小版本為1.7.7及以上。

    說明

    最新小版本將提供更豐富的功能與穩定的服務，建議將執行個體的小版本升級到最新，具體操作請參見升級小版本。如果您的執行個體為叢集執行個體或讀寫分離架構，請將代理節點的小版本也升級到最新，否則可能出現命令無法識別的情況。

    注意事項

    操作對象為Tair執行個體中的TairRoaring資料。

    命令列表

    類型

    命令

    文法

    說明

    版本變更

    寫操作

    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]

    設定Roaring Bitmap中指定位移量（offset）的bit值為1，支援傳入多個值。

    說明

    在TairRoaring V2版本中，建議使用TR.SETBITS代替該命令。

    -

    TR.SETINTARRAY

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

    根據傳入的整型數組，建立對應的Roaring Bitmap，該命令會重設（覆蓋）已存在的Roaring Bitmap對象。

    說明

    在TairRoaring V2版本中，建議使用TR.SETBITS代替該命令。

    -

    TR.SETBITARRAY

    TR.SETBITARRAY key value

    根據傳入的bit（由0和1組成的字串），建立對應的Roaring Bitmap。若目標Key已存在則會重設（覆蓋）原有資料。

    說明

    在TairRoaring V2版本中，建議使用TR.APPENDBITARRAY代替該命令。

    -

    TR.BITOP

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

    對Roaring Bitmap執行集合運算操作，計算結果儲存在destkey中，支援AND、OR、XOR、NOT和DIFF集合運算類型。

    說明

    該命令在叢集架構執行個體中不支援執行跨Slot的Key。

    -

    TR.BITOPCARD

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

    對Roaring Bitmap執行集合運算操作，支援AND、OR、XOR、NOT和DIFF集合運算類型。

    說明

    該命令在叢集架構執行個體中不支援執行跨Slot的Key。

    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]

    從Roaring Bitmap中指定位移量（start_offset）開始向後掃描，返回若干（count）個bit值為1的位移量，返回的遊標（cursor）為Roaring Bitmap對應的offset。

    說明

    在迭代過程中被添加、被刪除的元素的掃描結果存在不確定性，即可能被返回，也可能不會。

    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

    擷取兩個Roaring Bitmap之間的Jaccard相似係數，Jaccard係數值越大，Roaring Bitmap的相似性越高。

    說明

    該命令在叢集架構執行個體中不支援執行跨Slot的Key。

    V2.2新增

    TR.CONTAINS

    TR.CONTAINS key1 key2

    計算key2所對應的Roaring Bitmap是否包含key1所對應的Roaring Bitmap（即key1是否為key2的子集），若包含則返回1，否則返回0。

    說明

    該命令在叢集架構執行個體中不支援執行跨Slot的Key。

    V2.2新增

    TR.RANK

    TR.RANK key offset

    擷取Roaring Bitmap中從offset為0到指定offset區間內（包含該值），bit值為1的數量。

    V2.2新增

    通用

    DEL

    DEL key [key ...]

    使用原生Redis的DEL命令可以刪除一條或多條TairRoaring資料。

    -

    說明

    • 本文關於命令文法的定義：

      • 大寫關鍵字：命令關鍵字。

      • 斜體：變數。

      • [options]：選擇性參數，不在括弧中的參數為必選。

      • A|B：該組參數互斥，請進行二選一或多選一。

      • ...：前面的內容可重複。

    • 本文關於時間複雜度的特別約定：

      • C表示參數的數量（argc）或範圍（range）。

      • M表示該種資料結構內部bit值為1的數量（例如List的node數量，Hash的field數量等）。

    TR.SETBIT

    類別

    說明

    文法

    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

    類別

    說明

    文法

    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

    類別

    說明

    文法

    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

    類別

    說明

    文法

    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

    類別

    說明

    文法

    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

    類別

    說明

    文法

    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

    類別

    說明

    文法

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

    時間複雜度

    O(C)

    命令描述

    設定Roaring Bitmap中指定位移量（offset）的bit值為1，支援傳入多個值。

    說明

    在TairRoaring V2版本中，建議使用TR.SETBITS代替該命令。

    選項

    • Key：Key名稱（TairRoaring資料結構）。

    • value：整型數字，表示待設定的bit位，取值範圍為0 ~ 4294967296。

    傳回值

    • 執行成功：返回OK。

    • 其他情況返回相應的異常資訊。

    樣本

    命令樣本：

    TR.APPENDINTARRAY foo 9 10

    返回樣本：

    OK

    TR.SETINTARRAY

    類別

    說明

    文法

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

    時間複雜度

    O(C)

    命令描述

    根據傳入的整型數組來設定對應的Roaring Bitmap，若目標Key已存在則會重設（覆蓋）原有資料。

    說明

    在TairRoaring V2版本中，建議使用TR.SETBITS代替該命令。

    選項

    • Key：Key名稱（TairRoaring資料結構）。

    • value：整型數字，表示待設定的bit位。

    傳回值

    • 執行成功：返回OK。

    • 其他情況返回相應的異常資訊。

    樣本

    命令樣本：

    TR.SETINTARRAY foo 2 4 5 6

    返回樣本：

    OK

    TR.SETBITARRAY

    類別

    說明

    文法

    TR.SETBITARRAY key value

    時間複雜度

    O(C)

    命令描述

    根據傳入的bit（由0和1組成的字串），建立對應的Roaring Bitmap。若目標Key已存在則會重設（覆蓋）原有資料。

    說明

    在TairRoaring V2版本中，建議使用TR.APPENDBITARRAY代替該命令。

    選項

    • key：Key名稱（TairRoaring資料結構）。

    • value：由0和1構成的字串，即需要設定的bit數組。

    傳回值

    • 執行成功：返回OK。

    • 其他情況返回相應的異常資訊。

    樣本

    命令樣本：

    tr.setbitarray foo 10101001

    返回樣本：

    OK

    TR.BITOP

    類別

    說明

    文法

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

    時間複雜度

    O(C * M)

    命令描述

    對Roaring Bitmap執行集合運算操作，計算結果儲存在destkey中，支援AND、OR、XOR、NOT和DIFF集合運算類型。

    說明

    該命令在叢集架構執行個體中不支援執行跨Slot的Key。

    選項

    • 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

    類別

    說明

    文法

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

    時間複雜度

    O(C * M)

    命令描述

    對Roaring Bitmap執行集合運算操作，支援AND、OR、XOR、NOT和DIFF集合運算類型。

    說明

    該命令在叢集架構執行個體中不支援執行跨Slot的Key。

    選項

    • 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

    類別

    說明

    文法

    TR.OPTIMIZE key

    時間複雜度

    O(M)

    命令描述

    最佳化Roaring Bitmap的儲存空間。如果目標對象相對較大，且建立後以唯讀操作為主，可以主動執行此命令。

    選項

    • Key：Key名稱（TairRoaring資料結構）。

    傳回值

    • 執行成功：返回OK。

    • 若key不存在：返回nil。

    • 其他情況返回相應的異常資訊。

    樣本

    命令樣本：

    TR.OPTIMIZE foo

    返回樣本：

    OK

    TR.GETBIT

    類別

    說明

    文法

    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

    類別

    說明

    文法

    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

    類別

    說明

    文法

    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

    類別

    說明

    文法

    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

    類別

    說明

    文法

    TR.SCAN key start_offset [COUNT count]

    時間複雜度

    O(C)

    命令描述

    從Roaring Bitmap中指定位移量（start_offset）開始向後掃描，返回若干（count）個bit值為1的位移量，返回的遊標（cursor）為Roaring Bitmap對應的offset。

    說明

    在迭代過程中被添加、被刪除的元素的掃描結果存在不確定性，即可能被返回，也可能不會。

    選項

    • 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

    類別

    說明

    文法

    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

    類別

    說明

    文法

    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

    類別

    說明

    文法

    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

    類別

    說明

    文法

    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

    類別

    說明

    文法

    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

    類別

    說明

    文法

    TR.JACCARD key1 key2

    時間複雜度

    O(M)

    命令描述

    擷取兩個Roaring Bitmap之間的Jaccard相似係數，Jaccard係數值越大，Roaring Bitmap的相似性越高。

    說明

    該命令在叢集架構執行個體中不支援執行跨Slot的Key。

    選項

    • Key：Key名稱（TairRoaring資料結構）。

    傳回值

    • 執行成功：返回Jaccard相似係數（Double類型）。

    • 其他情況返回相應的異常資訊。

    樣本

    命令樣本：

    TR.JACCARD foo1 foo2

    返回樣本：

    "0.20000000000000001"

    TR.CONTAINS

    類別

    說明

    文法

    TR.CONTAINS key1 key2

    時間複雜度

    O(M)

    命令描述

    計算key2所對應的Roaring Bitmap是否包含key1所對應的Roaring Bitmap（即key1是否為key2的子集），若包含則返回1，否則返回0。

    說明

    該命令在叢集架構執行個體中不支援執行跨Slot的Key。

    選項

    • 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

    類別

    說明

    文法

    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對象已存在，且不支援覆蓋。

    說明

    V2.2版之後將不會產生該報錯。

    ERR key not found

    Roaring Bitmap對象不存在, 不支援操作。

    說明

    V2.2版之後將不會產生該報錯。