Hologres：RoaringBitmap函數

背景資訊

RoaringBitmap是一種高效的Bitmap壓縮演算法，目前已被廣泛應用在各種語言和各種巨量資料平台。適合計算超高基維的，常用於去重、標籤篩選、時間序列等計算中。

RoaringBitmap演算法是將32位的INT類型資料劃分為2¹⁶個資料區塊（Chunk），每一個資料區塊對應整數的高16位，並使用一個容器（Container）來存放一個數值的低16位。RoaringBitmap將這些容器儲存在一個動態數組中，作為一級索引。容器使用兩種不同的結構：數組容器（Array Container）和位元影像容器（Bitmap Container）。數組容器存放稀疏的資料，位元影像容器存放稠密的資料。如果一個容器裡面的整數數量小於4096，就用數組容器來儲存值。若大於4096，就用位元影像容器來儲存值。

採用這種儲存結構，RoaringBitmap可以快速檢索一個特定的值。在做位元影像計算（AND、OR、XOR）時，RoaringBitmap提供了相應的演算法來高效地實現在兩種容器之間的運算。使得RoaringBitmap無論在儲存和計算效能上都表現優秀。

使用限制

操作符列表

以下操作符支援處理RoaringBitmap和RoaringBitmap64類型的資料。

Bitmap函數列表

• 支援處理RoaringBitmap和RoaringBitmap64類型的函數

  函數名	輸入類型	輸出類型	描述	樣本
  rb_build_agg	INTEGER|BIGINT	入參的資料類型為： INTEGER時，返回RoaringBitmap類型。 BIGINT時，返回RoaringBitmap64類型。	將Offset彙總成RoaringBitmap。 說明 僅Hologres V3.1及以上版本支援BIGINT入參類型，並返回RoaringBitmap64類型。	rb_build_agg(1)
  rb_cardinality	RoaringBitmap | RoaringBitmap64	INTEGER	統計基數。	rb_cardinality(rb_build('{1,2,3,4,5}'))
  rb_and_cardinality	RoaringBitmap | RoaringBitmap64，RoaringBitmap | RoaringBitmap64	INTEGER	And計算並返回基數。	rb_and_cardinality(rb_build('{1,2,3}'),rb_build('{3,4,5}'))
  rb_or_cardinality	RoaringBitmap | RoaringBitmap64，RoaringBitmap | RoaringBitmap64	INTEGER	Or計算並返回基數。	rb_or_cardinality(rb_build('{1,2,3}'),rb_build('{3,4,5}'))
  rb_range	RoaringBitmap | RoaringBitmap64，BIGINT，BIGINT	RoaringBitmap | RoaringBitmap64	返回從起始位置（包含）到結束位置（不包含）範圍的新集合，位置從1開始計數。 說明 Hologres V1.3.16及以上版本支援。	rb_range(rb_build('{1,2,3}'), 2, 3)
  rb_minimum	RoaringBitmap | RoaringBitmap64	INTEGER	返回Bitmap中最小的Offset，如果Bitmap為空白則返回-1。	rb_minimum(rb_build('{1,2,3}'))
  rb_maximum	RoaringBitmap | RoaringBitmap64	INTEGER	返回Bitmap中最大的Offset，如果Bitmap為空白則返回0。	rb_maximum(rb_build('{1,2,3}'))
  rb_to_array	RoaringBitmap | RoaringBitmap64	INTEGER[]	返回Bitmap對應整型數組。	rb_to_array(rb_build('{1,2,3}'))
  rb_to_array_string	RoaringBitmap | RoaringBitmap64, TEXT	TEXT	返回Bitmap對應整型數組拼接的字串。	rb_to_array_string(rb_build('{1,2,3}'),',')

• 僅支援處理RoaringBitmap64類型的函數

  函數名	輸入類型	輸出類型	描述	樣本
  rb64_build	BIGINT[]	RoaringBitmap64	通過數組建立一個64位的RoaringBitmap。 說明 Hologres V3.1及以上版本支援。	--準備資料 CREATE TABLE public.tn ( id INT, num BIGINT[] ); INSERT INTO public.tn ("id", "num") VALUES (01, '{1,2}'); SELECT rb64_build (num) rb_num,num FROM public.tn; 返回結果如下。 rb_num num \x030100000000000000000000003a30000001000000000001001000000001000200 {1,2}

• 僅支援處理RoaringBitmap類型的函數

  函數名	輸入類型	輸出類型	描述	樣本
  rb_build	INTEGER[]	RoaringBitmap	通過數組建立一個32位RoaringBitmap。	--返回結果：\x3a3000000100000000000000100000000100 SELECT rb_build_agg(1);
  roaringbitmap_in	TEXT	RoaringBitmap	將TEXT類型轉換成RoaringBitmap類型。 說明 Hologres V2.1.33及以上版本支援。	--建立樣本表。 CREATE TABLE rb_text ( id int, a text ); --插入樣本資料。 INSERT INTO rb_text VALUES (1, '\x3a300000010000000000090010000000010002000300040005000600070008000900c800'); --將欄位a轉換成roaringbitmap類型，並進行and彙總運算。 SELECT rb_and_cardinality_agg (roaringbitmap_in (a::cstring)) FROM rb_text; --返回結果 rb_and_cardinality_agg| ----------------------- 10|
  rb_index	RoaringBitmap, INTEGER	BIGINT	返回此roaringbitmap中元素從0開始的索引，如果不存在則返回-1。 說明 Hologres V1.3.16及以上版本支援。	rb_index(rb_build('{1,2,3}'),3)
  rb_and_null2empty	RoaringBitmap，RoaringBitmap	RoaringBitmap	And計算。當輸入參數為Null時，按empty處理。 說明 Hologres V1.1.42及以上版本支援。	rb_and_null2empty(rb_build(null),rb_build('{3,4,5}'))
  rb_or_null2empty	RoaringBitmap，RoaringBitmap	RoaringBitmap	Or計算。當輸入為Null時，按empty處理。 說明 Hologres V1.1.42及以上版本支援。	rb_or_null2empty(rb_build(null),rb_build('{3,4,5}'))
  rb_andnot_null2empty	RoaringBitmap，RoaringBitmap	RoaringBitmap	AndNot計算。當輸入為Null時，按empty處理。 說明 Hologres V1.1.42及以上版本支援。	rb_andnot_null2empty(rb_build(null),rb_build('{3,4,5}'))
  rb_and_null2empty_cardinality	RoaringBitmap，RoaringBitmap	INTEGER	And計算並返回基數。當輸入為Null時，按empty處理。 說明 Hologres V1.1.42及以上版本支援。	rb_and_null2empty_cardinality(rb_build(null),rb_build('{3,4,5}'))
  rb_or_null2empty_cardinality	RoaringBitmap，RoaringBitmap	INTEGER	Or計算並返回基數。當輸入為Null時，按empty處理。 說明 Hologres V1.1.42及以上版本支援。	rb_or_null2empty_cardinality(rb_build(null),rb_build('{3,4,5}'))
  rb_xor_cardinality	RoaringBitmap，RoaringBitmap	INTEGER	Xor計算並返回基數。	rb_xor_cardinality(rb_build('{1,2,3}'),rb_build('{3,4,5}'))
  rb_andnot_cardinality	RoaringBitmap，RoaringBitmap	INTEGER	AndNot計算並返回基數。	rb_andnot_cardinality(rb_build('{1,2,3}'),rb_build('{3,4,5}'))
  rb_andnot_null2empty_cardinality	RoaringBitmap，RoaringBitmap	INTEGER	AndNot計算並返回基數。當輸入為Null時，按empty處理。 說明 Hologres V1.1.42及以上版本支援。	rb_andnot_null2empty_cardinality(rb_build(null),rb_build('{3,4,5}'))
  rb_is_empty	RoaringBitmap	BOOLEAN	判斷是否為空白的Bitmap。	rb_is_empty(rb_build('{1,2,3,4,5}'))
  rb_fill	RoaringBitmap，BIGINT，BIGINT	RoaringBitmap	填寫指定範圍（不包括range_end）。 說明 Hologres V1.3.16及以上版本支援。	rb_fill(rb_build('{1,2,3}'), 5, 7)
  rb_clear	RoaringBitmap，BIGINT，BIGINT	RoaringBitmap	清除指定範圍（不包括 range_end）。 說明 Hologres V1.3.16及以上版本支援。	rb_clear(rb_build('{1,2,3}'), 2, 3)
  rb_contains_bitmap	RoaringBitmap，RoaringBitmap	BOOLEAN	判斷第一個Bitmap是否包含第二個Bitmap。	rb_contains(rb_build('{1,2,3}'),rb_build('{3}'))
  rb_flip	RoaringBitmap,INTEGER,INTEGER	RoaringBitmap	翻轉Bitmap中特定的Offset段。	rb_flip(rb_build('{1,2,3}'),2,3)
  rb_range_cardinality	RoaringBitmap, BIGINT, BIGINT	BIGINT	返回從起始位置（包含）到結束位置（不包含）範圍的基數，位置從1開始計數。 說明 Hologres V1.3.16及以上版本支援。	rb_range_cardinality(rb_build('{1,2,3}'), 2, 3)
  rb_rank	RoaringBitmap,INTEGER	INTEGER	返回Bitmap中小於等於指定Offset的基數。	rb_rank(rb_build('{1,2,3}'),3)
  rb_jaccard_dist	RoaringBitmap，RoaringBitmap	DOUBLE PRECISION	返回兩個Bitmap的Jaccard距離（或Jaccard相似係數）。 說明 Hologres V1.3.16及以上版本支援。	rb_jaccard_dist(rb_build('{1,2,3}'), rb_build('{3,4}'))
  rb_select	RoaringBitmap, bitset_limit bigint, bitset_offset bigint=0, reverse boolean=false, range_start bigint=-2147483648, range_end bigint=2147483647	RoaringBitmap	返回範圍 [range_start,range_end) 之間Bitmap的子集 [bitset_offset,bitset_offset+bitset_limit)。	rb_select(rb_build('{1,2,3,4,5,6,7,8,9}'), 5, 2)
  rb_iterate	RoaringBitmap	Set of Integer	返回Offset List。	rb_iterate(rb_build('{1,2,3}'))

Bitmap彙總函式列表

• 支援處理RoaringBitmap和RoaringBitmap64類型的函數

  函數名	輸入類型	輸出類型	描述	樣本
  rb_or_agg	RoaringBitmap | RoaringBitmap64	與入參類型一致。	Or彙總計算。	rb_or_agg(rb_build('{1,2,3}'))
  rb_and_agg	RoaringBitmap | RoaringBitmap64	與入參類型一致。	And彙總計算。	rb_and_agg(rb_build('{1,2,3}'))
  rb_or_cardinality_agg	RoaringBitmap | RoaringBitmap64	INTEGER	Or彙總計算並返回其基數。	rb_or_cardinality_agg(rb_build('{1,2,3}'))
  rb_and_cardinality_agg	RoaringBitmap | RoaringBitmap64	INTEGER	And彙總計算並返回其基數。	rb_and_cardinality_agg(rb_build('{1,2,3}'))

• 僅支援處理RoaringBitmap類型的函數

  函數名	輸入類型	輸出類型	描述	樣本
  rb_xor_agg	RoaringBitmap	RoaringBitmap	Xor彙總計算。	rb_xor_agg(rb_build('{1,2,3}'))
  rb_xor_cardinality_agg	RoaringBitmap	INTEGER	Xor彙總計算並返回其基數。	rb_xor_cardinality_agg(rb_build('{1,2,3}'))

其他Bitmap函數

以下函數僅支援處理RoaringBitmap類型的資料。

使用樣本

如下內容將為您介紹RoaringBitmap函數完整的使用樣本。

1. 載入RoaringBitmap函數外掛程式。

   CREATE EXTENSION roaringbitmap;

2. 建立帶有RoaringBitmap資料類型的表。

   --建立名稱為t1的表
   CREATE TABLE public.t1 (id integer, bitmap roaringbitmap);

3. 使用rb_build函數插入RoaringBitmap的資料。

   --數組位置對應的BIT值為1
   INSERT INTO public.t1 SELECT 1,RB_BUILD(ARRAY[1,2,3,4,5,6,7,8,9,200]);
   
   --將輸入的多條記錄的值對應位置的BIT值設定為1，最後彙總為一個RoaringBitmap  
   INSERT INTO public.t1 SELECT 2,RB_BUILD_AGG(e) FROM GENERATE_SERIES(1,100) e;

4. 進行Bitmap計算（OR、AND、XOR、ANDNOT）。

   SELECT  RB_OR(a.bitmap,b.bitmap)
   FROM    (
               SELECT  bitmap
               FROM    public.t1
               WHERE   id = 1
           ) AS a
           ,(
               SELECT  bitmap
               FROM    public.t1
               WHERE   id = 2
           ) AS b
   ;

5. 進行Bitmap彙總計算（OR、AND、XOR、BUILD），並產生新的RoaringBitmap類型。

   SELECT RB_OR_AGG(bitmap) FROM public.t1;
   SELECT RB_AND_AGG(bitmap) FROM public.t1;
   SELECT RB_XOR_AGG(bitmap) FROM public.t1;
   SELECT RB_BUILD_AGG(id) FROM public.t1;

6. 統計基數（Cardinality），即統計RoaringBitmap中包含多少個位置為1的BIT位。

   SELECT RB_CARDINALITY(bitmap) FROM public.t1;

7. 從RoaringBitmap中返回位置為1的BIT下標（即位置值）。

   SELECT RB_ITERATE(bitmap) FROM public.t1 WHERE id = 1;

8. 將RoaringBitmap轉換為數組結構。

   SELECT RB_TO_ARRAY(bitmap) FROM public.t1 WHERE id = 1;