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的數量,其他內容無變化。
2021年9月13日發布TairRoaring V1版本,請將小版本升級至1.7.20及以上。
2022年3月11日發布TairRoaring V2版本,請將小版本升級至1.7.27及以上。
該版本最佳化了部分命令的實現,提升了效能。新增TR.SETBITS、TR.CLEARBITS等9個命令,向前相容擴充2個命令,更新1個命令,更名1個命令。
2022年4月20日發布TairRoaring V2.2版本,請將小版本升級至1.8.1及以上。
該版本新增TR.JACCARD、TR.CONTAINS、TR.RANK命令,更新部分命令在key不存在時的返回錯誤(移除了
ERR key not found
)。
最佳實務
前提條件
注意事項
操作對象為Tair執行個體中的TairRoaring資料。
命令列表
類型 | 命令 | 文法 | 說明 | 版本變更 |
寫操作 |
| 設定Roaring Bitmap中指定位移量(offset)的bit值(1或者0),並返回該bit位之前的值,Roaring Bitmap的位移量(offset)從0開始。 | -(表示未更新) | |
| 設定Roaring Bitmap中指定位移量(offset)的bit值為1,支援傳入多個值。 | V2新增 | ||
| 設定Roaring Bitmap中指定位移量(offset)的bit值為0,若原值為0則不操作,支援傳入多個值。 | V2新增 | ||
| 設定Roaring Bitmap中指定區間(位移量)的bit值為1。 | V2更新,更新傳回值為成功設定bit值為1的數量。 | ||
| 將由連續的0或1組成的bit數組(bitarray)插入到Roaring Bitmap中指定位移量(offset)之後的位置,並覆蓋原有資料。 | V2新增 | ||
| 對Roaring Bitmap中指定區間(位移量)的bit值執行位反轉(1反轉為0;0反轉為1)。若指定key不存在,則自動建立目標key,並以空Roaring Bitmap對指定區間的bit值執行位反轉。 | V2新增 | ||
| 設定Roaring Bitmap中指定位移量(offset)的bit值為1,支援傳入多個值。 說明 在TairRoaring V2版本中,建議使用TR.SETBITS代替該命令。 | - | ||
| 根據傳入的整型數組,建立對應的Roaring Bitmap,該命令會重設(覆蓋)已存在的Roaring Bitmap對象。 說明 在TairRoaring V2版本中,建議使用TR.SETBITS代替該命令。 | - | ||
| 根據傳入的bit(由0和1組成的字串),建立對應的Roaring Bitmap。若目標Key已存在則會重設(覆蓋)原有資料。 說明 在TairRoaring V2版本中,建議使用TR.APPENDBITARRAY代替該命令。 | - | ||
| 對Roaring Bitmap執行集合運算操作,計算結果儲存在destkey中,支援AND、OR、XOR、NOT和DIFF集合運算類型。 說明 該命令在叢集架構執行個體中不支援執行跨Slot的Key。 | - | ||
| 對Roaring Bitmap執行集合運算操作,支援AND、OR、XOR、NOT和DIFF集合運算類型。 說明 該命令在叢集架構執行個體中不支援執行跨Slot的Key。 | V2新增 | ||
| 最佳化Roaring Bitmap的儲存空間。如果目標對象相對較大,且建立後以唯讀操作為主,可以主動執行此命令。 | - | ||
讀操作 |
| 擷取Roaring Bitmap中指定位移量(offset)的bit值。 | - | |
| 擷取Roaring Bitmap中指定位移量(offset)的bit值,支援查詢多個值。 | V2新增 | ||
| 擷取Roaring Bitmap中指定區間(位移量)bit值為1的數量。 | V2更新,向前相容。 | ||
| 擷取第count個bit值為1或者0的位移量,count為選擇性參數,預設為1(表示從前向後計數的第一個)。 | V2更新,向前相容。 | ||
| 從Roaring Bitmap中指定位移量(start_offset)開始向後掃描,返回若干(count)個bit值為1的位移量,返回的遊標(cursor)為Roaring Bitmap對應的offset。 說明 在迭代過程中被添加、被刪除的元素的掃描結果存在不確定性,即可能被返回,也可能不會。 | V2新增 | ||
| 擷取Roaring Bitmap指定區間中bit值為1的位移量。 | V1的TR.RANGEINTARRAY命令,V2重新命名為TR.RANGE。 | ||
| 擷取Roaring Bitmap指定區間中所有bit值(0、1)組成的字串。 | V2新增 | ||
| 擷取Roaring Bitmap中bit值為1的最小位移量(首個),不存在時返回-1。 | - | ||
| 擷取Roaring Bitmap中bit值為1的最大位移量,不存在時返回-1。 | - | ||
| 擷取Roaring Bitmap的統計資訊,包括各種容器的數量以及記憶體使用量狀況等資訊。 | V2新增 | ||
| 擷取兩個Roaring Bitmap之間的Jaccard相似係數,Jaccard係數值越大,Roaring Bitmap的相似性越高。 說明 該命令在叢集架構執行個體中不支援執行跨Slot的Key。 | V2.2新增 | ||
| 計算key2所對應的Roaring Bitmap是否包含key1所對應的Roaring Bitmap(即key1是否為key2的子集),若包含則返回1,否則返回0。 說明 該命令在叢集架構執行個體中不支援執行跨Slot的Key。 | V2.2新增 | ||
| 擷取Roaring Bitmap中從offset為0到指定offset區間內(包含該值),bit值為1的數量。 | V2.2新增 | ||
通用 |
| 使用原生Redis的DEL命令可以刪除一條或多條TairRoaring資料。 | - |
本文關於命令文法的定義:
大寫關鍵字
:命令關鍵字。斜體
:變數。[options]
:選擇性參數,不在括弧中的參數為必選。A|B
:該組參數互斥,請進行二選一或多選一。...
:前面的內容可重複。
本文關於時間複雜度的特別約定:
C表示參數的數量(argc)或範圍(range)。
M表示該種資料結構內部bit值為1的數量(例如List的node數量,Hash的field數量等)。
TR.SETBIT
類別 | 說明 |
文法 |
|
時間複雜度 | O(1) |
命令描述 | 設定Roaring Bitmap中指定位移量(offset)的bit值(1或者0),並返回該bit位之前的值,Roaring Bitmap的位移量(offset)從0開始。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.SETBITS
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 設定Roaring Bitmap中指定位移量(offset)的bit值為1,支援傳入多個值。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.CLEARBITS
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 設定Roaring Bitmap中指定位移量(offset)的bit值為0,若原值為0則不操作,支援傳入多個值。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.SETRANGE
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 設定Roaring Bitmap中指定區間(位移量)的bit值為1。 例如執行 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.APPENDBITARRAY
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 將由連續的0或1組成的bit數組(bitarray)插入到Roaring Bitmap中指定位移量(offset)之後的位置,並覆蓋原有資料。 |
選項 |
|
傳回值 |
|
樣本 | 提前執行 命令樣本:
返回樣本:
此時,Roaring Bitmap foo為“101101”。 |
TR.FLIPRANGE
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 對Roaring Bitmap中指定區間(位移量)的bit值執行位反轉(1反轉為0;0反轉為1)。若指定key不存在,則自動建立目標key,並以空Roaring Bitmap對指定區間的bit值執行位反轉。 |
選項 |
|
傳回值 |
|
樣本 | 提前執行 命令樣本:
返回樣本:
此時,Roaring Bitmap foo為“01001”。 |
TR.APPENDINTARRAY
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 設定Roaring Bitmap中指定位移量(offset)的bit值為1,支援傳入多個值。 說明 在TairRoaring V2版本中,建議使用TR.SETBITS代替該命令。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.SETINTARRAY
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 根據傳入的整型數組來設定對應的Roaring Bitmap,若目標Key已存在則會重設(覆蓋)原有資料。 說明 在TairRoaring V2版本中,建議使用TR.SETBITS代替該命令。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.SETBITARRAY
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 根據傳入的bit(由0和1組成的字串),建立對應的Roaring Bitmap。若目標Key已存在則會重設(覆蓋)原有資料。 說明 在TairRoaring V2版本中,建議使用TR.APPENDBITARRAY代替該命令。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.BITOP
類別 | 說明 |
文法 |
|
時間複雜度 | O(C * M) |
命令描述 | 對Roaring Bitmap執行集合運算操作,計算結果儲存在destkey中,支援AND、OR、XOR、NOT和DIFF集合運算類型。 說明 該命令在叢集架構執行個體中不支援執行跨Slot的Key。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.BITOPCARD
類別 | 說明 |
文法 |
|
時間複雜度 | O(C * M) |
命令描述 | 對Roaring Bitmap執行集合運算操作,支援AND、OR、XOR、NOT和DIFF集合運算類型。 說明 該命令在叢集架構執行個體中不支援執行跨Slot的Key。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.OPTIMIZE
類別 | 說明 |
文法 |
|
時間複雜度 | O(M) |
命令描述 | 最佳化Roaring Bitmap的儲存空間。如果目標對象相對較大,且建立後以唯讀操作為主,可以主動執行此命令。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.GETBIT
類別 | 說明 |
文法 |
|
時間複雜度 | O(1) |
命令描述 | 擷取Roaring Bitmap中指定位移量(offset)的bit值。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.GETBITS
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 擷取Roaring Bitmap中指定位移量(offset)的bit值,支援查詢多個值。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.BITCOUNT
類別 | 說明 |
文法 |
|
時間複雜度 | O(M) |
命令描述 | 擷取Roaring Bitmap中指定區間(位移量)bit值為1的數量。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.BITPOS
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 擷取第count個bit值為1或者0的位移量,count為選擇性參數,預設為1(表示從前向後計數的第一個)。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.SCAN
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 從Roaring Bitmap中指定位移量(start_offset)開始向後掃描,返回若干(count)個bit值為1的位移量,返回的遊標(cursor)為Roaring Bitmap對應的offset。 說明 在迭代過程中被添加、被刪除的元素的掃描結果存在不確定性,即可能被返回,也可能不會。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.RANGE
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 擷取Roaring Bitmap指定區間中bit值為1的位移量。 |
選項 |
|
傳回值 |
|
樣本 | 提前執行 命令樣本:
返回樣本:
|
TR.RANGEBITARRAY
類別 | 說明 |
文法 |
|
時間複雜度 | O(C) |
命令描述 | 擷取Roaring Bitmap指定區間中所有bit值(0、1)組成的字串。 |
選項 |
|
傳回值 |
|
樣本 | 提前執行 命令樣本:
返回樣本:
|
TR.MIN
類別 | 說明 |
文法 |
|
時間複雜度 | O(1) |
命令描述 | 擷取Roaring Bitmap中bit值為1的最小位移量(首個),不存在時返回-1。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.MAX
類別 | 說明 |
文法 |
|
時間複雜度 | O(1) |
命令描述 | 擷取Roaring Bitmap中bit值為1的最大位移量,不存在時返回-1。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.STAT
類別 | 說明 |
文法 |
|
時間複雜度 | O(M) |
命令描述 | 擷取Roaring Bitmap的統計資訊,包括各種容器的數量以及記憶體使用量狀況等資訊。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.JACCARD
類別 | 說明 |
文法 |
|
時間複雜度 | O(M) |
命令描述 | 擷取兩個Roaring Bitmap之間的Jaccard相似係數,Jaccard係數值越大,Roaring Bitmap的相似性越高。 說明 該命令在叢集架構執行個體中不支援執行跨Slot的Key。 |
選項 |
|
傳回值 |
|
樣本 | 命令樣本:
返回樣本:
|
TR.CONTAINS
類別 | 說明 |
文法 |
|
時間複雜度 | O(M) |
命令描述 | 計算key2所對應的Roaring Bitmap是否包含key1所對應的Roaring Bitmap(即key1是否為key2的子集),若包含則返回1,否則返回0。 說明 該命令在叢集架構執行個體中不支援執行跨Slot的Key。 |
選項 |
|
傳回值 |
|
樣本 | 提前執行 命令樣本:
返回樣本:
|
TR.RANK
類別 | 說明 |
文法 |
|
時間複雜度 | O(M) |
命令描述 | 擷取Roaring Bitmap中從offset為0到指定offset區間內(包含該值),bit值為1的數量。 |
選項 |
|
傳回值 |
|
樣本 | 提前執行 命令樣本:
返回樣本:
|
異常傳回值說明
錯誤資訊 | 說明 |
| 物件類型錯誤:Key不是TairRoaring對象。 |
| 參數類型錯誤:無法按照32-bit整型進行轉換。 |
| 參數非法:
|
| Roaring Bitmap對象已存在,且不支援覆蓋。 說明 V2.2版之後將不會產生該報錯。 |
| Roaring Bitmap對象不存在, 不支援操作。 說明 V2.2版之後將不會產生該報錯。 |