全部产品
Search

搜索本产品

    实时数仓Hologres：RoaringBitmap函数

    文档中心

    实时数仓Hologres：RoaringBitmap函数

    更新时间：Dec 02, 2024

    本文将为您介绍在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;