文档

RoaringBitmap函数

更新时间:

本文将为您介绍在Hologres中RoaringBitmap函数的具体参数和使用。

背景信息

RoaringBitmap是一种高效的Bitmap压缩算法,目前已被广泛应用在各种语言和各种大数据平台。适合计算超高基维的,常用于去重、标签筛选、时间序列等计算中。

RoaringBitmap算法是将32位的INT类型数据划分为216个数据块(Chunk),每一个数据块对应整数的高16位,并使用一个容器(Container)来存放一个数值的低16位。RoaringBitmap将这些容器保存在一个动态数组中,作为一级索引。容器使用两种不同的结构:数组容器(Array Container)和位图容器(Bitmap Container)。数组容器存放稀疏的数据,位图容器存放稠密的数据。如果一个容器里面的整数数量小于4096,就用数组容器来存储值。若大于4096,就用位图容器来存储值。

采用这种存储结构,RoaringBitmap可以快速检索一个特定的值。在做位图计算(AND、OR、XOR)时,RoaringBitmap提供了相应的算法来高效地实现在两种容器之间的运算。使得RoaringBitmap无论在存储和计算性能上都表现优秀。

使用限制

在Hologres中使用RoaringBitmap函数,具体限制如下:

  • 该函数仅Hologres V0.10及以上版本支持,请在Hologres管控台查看当前实例版本,如果您的实例是V0.10以下版本,请您使用自助升级或加入Hologres钉钉交流群反馈,详情请参见如何获取更多的在线支持?

  • 该函数仅独享实例支持,共享集群不支持。

  • 该函数默认加载到public Schema下,且只能加载到public Schema下,不能加载到其他Schema。

  • Hologres V1.3版本新增了若干RoaringBitmap函数(见函数列表描述备注),若您需要使用这些函数,请您使用自助升级或加入Hologres钉钉交流群反馈,详情请参见如何获取更多的在线支持?

  • RoaringBitmap函数在使用之前,需要执行以下语句开启extension才可以调用。extension是DB级别的函数,一个DB只需执行一次即可,新建DB需要重新执行。

    --创建extension
    CREATE EXTENSION roaringbitmap;

    如需卸载RoaringBitmap扩展,请执行如下命令。

    DROP EXTENSION roaringbitmap;
    重要

    不推荐使用DROP EXTENSION <extension_name> CASCADE;命令级联卸载Extension。CASCADE(级联)删除命令不仅会删除指定扩展本身,还会一并清除扩展数据(例如PostGIS数据、RoaringBitmap数据、Proxima数据、Binlog数据、BSI数据等)以及依赖该扩展的对象(包括元数据、表、视图、Server数据等)。

  • 不支持将RoaringBitmap设置为Bitmap或者Dictionary。

操作符列表

操作符

输入

输出

描述

示例

备注

&

roaringbitmap, roaringbitmap

roaringbitmap

And计算。

rb_build('{1,2,3}') & rb_build('{3,4,5}')

不涉及

|

roaringbitmap, roaringbitmap

roaringbitmap

Or计算。

rb_build('{1,2,3}') | rb_build('{3,4,5}')

不涉及

roaringbitmap, integer

roaringbitmap

rb_build('{1,2,3}') | 6

Hologres V1.3.16及以上版本支持。

integer, roaringbitmap

roaringbitmap

6 | rb_build('{1,2,3}')

Hologres V1.3.16及以上版本支持。

#

roaringbitmap, roaringbitmap

roaringbitmap

Xor计算。

rb_build('{1,2,3}') # rb_build('{3,4,5}')

不涉及

<<

roaringbitmap, bigint

roaringbitmap

Shift left计算。

rb_build('{1,2,3}') << 2

Hologres V1.3.16及以上版本支持。

>>

roaringbitmap, bigint

roaringbitmap

Shift right计算。

rb_build('{1,2,3}') >> 3

Hologres V1.3.16及以上版本支持。

-

roaringbitmap, roaringbitmap

roaringbitmap

AndNot计算。

rb_build('{1,2,3}') - rb_build('{3,4,5}')

Hologres V1.3.16及以上版本支持。

roaringbitmap, integer

roaringbitmap

rb_build('{1,2,3}') - 3

不涉及

@>

roaringbitmap, roaringbitmap

bool

判断是否为包含关系。

rb_build('{1,2,3}') @> rb_build('{3,4,5}')

不涉及

roaringbitmap, integer

bool

rb_build('{1,2,3}') @> 3

不涉及

<@

roaringbitmap, roaringbitmap

bool

判断是否为被包含关系。

rb_build('{1,2,3}') <@ rb_build('{3,4,5}')

不涉及

integer, roaringbitmap

bool

3 <@ rb_build('{1,2,3}')

不涉及

&&

roaringbitmap, roaringbitmap

bool

判断是否有重叠。

rb_build('{1,2,3}') && rb_build('{3,4,5}')

不涉及

=

roaringbitmap, roaringbitmap

bool

判断是否相等。

rb_build('{1,2,3}') = rb_build('{3,4,5}')

不涉及

<>

roaringbitmap, roaringbitmap

bool

判断是否不等。

rb_build('{1,2,3}') <> rb_build('{3,4,5}')

不涉及

Bitmap函数列表

Bitmap函数主要包括的函数及说明如所示:

函数名

输入

输出

描述

示例

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_build

integer[]

roaringbitmap

通过数组创建一个Bitmap。

说明

Hologres V1.3.39版本前只支持常量数组作为输入,V1.3.39版本开始支持ARRAY列作为输入。

rb_build('{1,2,3,4,5}')

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_cardinality

roaringbitmap

integer

统计基数。

rb_cardinality(rb_build('{1,2,3,4,5}'))

rb_and_cardinality

roaringbitmap,roaringbitmap

integer

And计算并返回基数。

rb_and_cardinality(rb_build('{1,2,3}'),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_cardinality

roaringbitmap,roaringbitmap

integer

Or计算并返回基数。

rb_or_cardinality(rb_build('{1,2,3}'),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

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

roaringbitmap,bigint,bigint

roaringbitmap

返回从起始位置(包含)到结束位置(不包含)范围的新集合,位置从1开始计数。

说明

Hologres V1.3.16及以上版本支持。

rb_range(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_minimum

roaringbitmap

integer

返回Bitmap中最小的Offset,如果Bitmap为空则返回-1。

rb_minimum(rb_build('{1,2,3}'))

rb_maximum

roaringbitmap

integer

返回Bitmap中最大的Offset,如果Bitmap为空则返回0。

rb_maximum(rb_build('{1,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)

说明

Hologres V1.3.16及以上版本支持。

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}'))

rb_to_array

roaringbitmap

integer[]

返回Bitmap对应整型数组。

rb_to_array(rb_build('{1,2,3}'))

rb_to_array_string

roaringbitmap, text

text

返回Bitmap对应整型数组拼接的字符串。

rb_to_array_string(rb_build('{1,2,3}'),',')

Bitmap聚合函数列表

Bitmap聚合函数主要包括的函数及说明如所示:

函数名

输入数据类型

输出数据类型

描述

示例

rb_build_agg

integer

roaringbitmap

将Offset聚合成bitmap。

rb_build_agg(1)

rb_or_agg

roaringbitmap

roaringbitmap

Or聚合计算。

rb_or_agg(rb_build('{1,2,3}'))

rb_and_agg

roaringbitmap

roaringbitmap

And聚合计算。

rb_and_agg(rb_build('{1,2,3}'))

rb_xor_agg

roaringbitmap

roaringbitmap

Xor聚合计算。

rb_xor_agg(rb_build('{1,2,3}'))

rb_or_cardinality_agg

roaringbitmap

integer

Or聚合计算并返回其基数。

rb_or_cardinality_agg(rb_build('{1,2,3}'))

rb_and_cardinality_agg

roaringbitmap

integer

And聚合计算并返回其基数。

rb_and_cardinality_agg(rb_build('{1,2,3}'))

rb_xor_cardinality_agg

roaringbitmap

integer

Xor聚合计算并返回其基数。

rb_xor_cardinality_agg(rb_build('{1,2,3}'))

其他Bitmap函数

函数名

输入数据类型

输出数据类型

描述

示例

roaringbitmap_text

text, bool

roaringbitmap

将text类型的二进制roaringbitmap数据反序列转换成roaringbitmap结构。第二个参数表示是否进行格式校验,建议选择true,否则会返回错误的Bitmap数据。

roaringbitmap_text(':0', true)

rb_to_text

roaringbitmap

text

将roaringbitmap结构转为text类型的二进制roaringbitmap数据输出。

rb_to_text(rb_build('{1,2,3}'))

使用示例

如下内容将为您介绍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;