AI 助理
备案控制台
文档
输入文档关键字查找
首页 实时数仓 Hologres 操作指南 函数参考 流量分析函数 RoaringBitmap函数

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;

上一篇：明细圈人函数下一篇：BSI函数
文档推荐