普通函数

函数接收一行记录或者一个BitMap64对象，返回一行结果。
这部分的函数接口，除第一个函数arrayToBitmap外，其它的均和社区函数接口保持一致，示例可以参考上一小节【Bit & Bitmap 函数】。

聚合函数

下述聚合函数接收多行记录，进行聚合操作，返回一行结果。

以下是具体的函数示例：

bitmapColumAnd

计算一列 bitmap 的交集。
语法

bitmapColumnAnd(bitmap_column)

参数
bitmap_column - BitMap64 类型的数据列。
返回值

• 一个 BitMap64 对象

示例

select bitmapColumnAnd(rbm) as result
from (
    select arrayToBitmap([1,2,3]) as rbm
    union all
    select arrayToBitmap([2,3,4]) as rbm
)

结果：

┌─result─┐
│ {2,3}  │
└────────┘

bitmapColumnOr

计算一列 bitmap 的并集。
语法

bitmapColumnOr(bitmap_column)

参数
bitmap_column - BitMap64 类型的数据列。
返回值

• 一个 BitMap64 对象

示例

select bitmapColumnOr(rbm) as result
from (
    select arrayToBitmap([1,2,3]) as rbm
    union all
    select arrayToBitmap([2,3,4]) as rbm
)

结果：

┌─result────┐
│ {1,2,3,4} │
└───────────┘

bitmapColumnXor

计算一列 bitmap 的异或集。
语法

bitmapColumnXor(bitmap_column)

参数
bitmap_column - BitMap64 类型的数据列。
返回值

• 一个 BitMap64 对象

示例

select bitmapColumnXor(rbm) as result
from (
    select arrayToBitmap([1,2,3]) as rbm
    union all
    select arrayToBitmap([2,3,4]) as rbm
)

结果：

┌─result─┐
│ {1,4}  │
└────────┘

bitmapColumnCardinality

计算一列 bitmap 的并集包含的元素个数。
语法

bitmapColumnCardinality(bitmap_column)

参数
bitmap_column - BitMap64 类型的数据列。
返回值

• 一个UInt64数，表示 bitmap元素个数。

示例

select bitmapColumnCardinality(rbm) as result
from (
    select arrayToBitmap([1,2,3]) as rbm
    union all
    select arrayToBitmap([2,3,4]) as rbm
)

结果：

┌─result─┐
│      4 │
└────────┘

bitmapColumnHas

判断一列 bitmap 中是否包含指定数值。
语法

bitmapColumnHas(bitmap_column, integer_number)

参数
bitmap_column - BitMap64 类型的数据列。
integer_number - 一个常量数值。类型为64位以内的正整数。
返回值

• 一个Bool 值，0 表示给定数值不存在，1 表示存在。
• 和函数bitmapContains的区别在于改函数对于一列 bitmap仅返回一行值，bitmapContains则是多行。

示例

select bitmapColumnHas(rbm, 3) as result
from (
    select arrayToBitmap([1,2,3]) as rbm
    union all
    select arrayToBitmap([2,3,4]) as rbm
)

结果：

┌─result─┐
│      1 │
└────────┘

bitmapFromColumn

从一列数值中构建一个BitMap64 对象。
语法

bitmapFromColumn(integer_column)

参数

• integer_column - 64 位以内的正整数列。

返回值

• 一个BitMap64 对象

示例

select bitmapFromColumn(number) as res from numbers(10);

结果：

┌─res───────────────────┐
│ {0,1,2,3,4,5,6,7,8,9} │
└───────────────────────┘

高阶聚合函数

这种函数有两个括号传递参数：

• 第一个括号称为parameter，用于控制聚合函数的行为 （控制流）
• 第二个括号称为argument，用于向聚合函数传递输入数据列 （数据流）

ByteHouse 提供了一系列聚合函数用于批量处理大量 bitmap 之间的复杂计算。通过给每个待计算的 bitmap编序号，并用序号书写表达出集合的交并差运算，ByteHouse 可以根据指定的运算表达式完成对应的 bitmap 运算，直接把计算可视化和简便化，极大提升了写 SQL的体验！
简单图示如下：

Tips: 如果存在相同编号idx的多行数据，聚合函数会自动把多行bitmap通过OR运算合并为一个，参与计算。最终计算时，一个idx对应一个bitmap。
以下是具体的函数说明

BitmapCount

依据用户指定的计算表达式，执行相应的bitmap运算，返回最终bitmap中元素个数。
语法：

BitMapCount(expr)(idx_column, bitmap_column)

参数

• expr - 使用数字或字符串表示的与(&)、或(|)、差(~)运算，&表示bitmap交集，|表示bitmap并集，~表示bitmap差集，该函数仅支持一个表达式。
• idx_column - 用于标记 bitmap的数据列，可以是整数列(通常为 Int16/32/64类型)，或者字符串列。
• bitmap_column - BitMap64 数据列。

注1：不要求idx_column数据和bitmap_column数据一一对应，如果idx_column存在重复数据，则值相同的多行 bitmap 会先进行并集运算，合并为一个唯一的 bitmap 参与计算。
注 2：当idx_column列类型位字符串时，不能包含如下保留字符：&, |, ~, ,, #, (, ), _和英文空格。

返回值

• UInt64 - 计算后的 bitmap 中元素个数。

示例

SELECT bitmapCount('a')(tag_value, uids) AS res
FROM
(
    SELECT
        'a' AS tag_value,
        arrayToBitmap([1, 2, 3]) AS uids
)

结果：

┌─res─┐
│   3 │
└─────┘

SELECT
    BitmapCount('((a&b)|c) ~ d')(tag_value, uids) AS res1,
    BitmapCount('((1&2)|3)~4')(multiIf(tag_value = 'a', toInt16(1), tag_value = 'b', toInt16(2), tag_value = 'c', toInt16(3), tag_value = 'd', toInt16(4), toInt16(0)) AS idx, uids) AS res2
FROM
(
    SELECT
        'a' AS tag_value,
        arrayToBitmap([1, 2, 3, 4, 5]) AS uids
    UNION ALL
    SELECT
        'b' AS tag_value,
        arrayToBitmap([3, 4, 5, 6]) AS uids
    UNION ALL
    SELECT
        'c' AS tag_value,
        arrayToBitmap([5, 7]) AS uids
    UNION ALL
    SELECT
        'd' AS tag_value,
        arrayToBitmap([7]) AS uids
)

结果

┌─res1─┬─res2─┐
│    3 │    3 │
└──────┴──────┘

BitmapExtract

依据用户指定的计算表达式，执行相应的bitmap运算，返回最终bitmap。
语法：

BitMapExtract(expr)(idx_column, bitmap_column)

参数

• expr - 使用数字或字符串表示的与(&)、或(|)、差(~)运算，&表示bitmap交集，|表示bitmap并集，~表示bitmap差集，该函数仅支持一个表达式。
• idx_column - 用于标记 bitmap的数据列，可以是整数列(通常为 Int16/32/64类型)，或者字符串列。
• bitmap_column - BitMap64 数据列。

注1：不要求idx_column数据和bitmap_column数据一一对应，如果idx_column存在重复数据，则值相同的多行 bitmap 会先进行并集运算，合并为一个唯一的 bitmap 参与计算。
注 2：当idx_column列类型位字符串时，不能包含如下保留字符：&, |, ~, ,, #, (, ), _和英文空格。

返回值

• BitMap64 - 计算后的 bitmap 对象。

示例

SELECT bitmapExtract('a')(tag_value, uids) AS res
FROM
(
    SELECT
        'a' AS tag_value,
        arrayToBitmap([1, 2, 3]) AS uids
)

结果

┌─res─────┐
│ {1,2,3} │
└─────────┘

SELECT
    BitmapExtract('((a&b)|c) ~ d')(tag_value, uids) AS res1,
    BitmapExtract('((1&2)|3)~4')(multiIf(tag_value = 'a', toInt16(1), tag_value = 'b', toInt16(2), tag_value = 'c', toInt16(3), tag_value = 'd', toInt16(4), toInt16(0)) AS idx, uids) AS res2
FROM
(
    SELECT
        'a' AS tag_value,
        arrayToBitmap([1, 2, 3, 4, 5]) AS uids
    UNION ALL
    SELECT
        'b' AS tag_value,
        arrayToBitmap([3, 4, 5, 6]) AS uids
    UNION ALL
    SELECT
        'c' AS tag_value,
        arrayToBitmap([5, 7]) AS uids
    UNION ALL
    SELECT
        'd' AS tag_value,
        arrayToBitmap([7]) AS uids
)

结果：

┌─res1────┬─res2────┐
│ {3,4,5} │ {3,4,5} │
└─────────┴─────────┘

BitmapMultiCount

依据用户指定的一组计算表达式，每组执行相应的bitmap运算，返回每组最终bitmap中元素个数。
语法：

BitmapMultiCount(expr1, expr2, expr3,...)(idx_column, bitmap_column)

参数

• expr - 使用数字或字符串表示的与(&)、或(|)、差(~)运算，&表示bitmap交集，|表示bitmap并集，~表示bitmap差集，该函数支持多个表达式。
• idx_column - 用于标记 bitmap的数据列，可以是整数列(通常为 Int16/32/64类型)，或者字符串列。
• bitmap_column - BitMap64 数据列。

注1：不要求idx_column数据和bitmap_column数据一一对应，如果idx_column存在重复数据，则值相同的多行 bitmap 会先进行并集运算，合并为一个唯一的 bitmap 参与计算。
注2：当idx_column列类型位字符串时，不能包含如下保留字符：&, |, ~, ,, #, (, ), _和英文空格。
注3：支持结果复用。比如 expr1='a&b', expr2='(a&b)|c。那么可以简化 expr2 的写法为expr2='_1|c'。使用下划线+数字可以指定某个已经出现过的表达式，可以简化复杂表达式写法。

返回值

• UInt64数组 - 每个表达式计算后的 bitmap 中元素个数。数组大小和表达式个数相等。

示例

SELECT BitmapMultiCount('a')(tag_value, uids) AS res
FROM
(
    SELECT
        'a' AS tag_value,
        arrayToBitmap([1, 2, 3]) AS uids
)

┌─res─┐
│ [3] │
└─────┘

SELECT BitmapMultiCount('1&2', '(1&2)|3', '_1|3', '((1&2)|3) ~ 4', '_2~4')(tag_value, uids) AS res
FROM
(
    SELECT
        toInt32(1) AS tag_value,
        arrayToBitmap([1, 2, 3, 4, 5]) AS uids
    UNION ALL
    SELECT
        toInt32(2) AS tag_value,
        arrayToBitmap([3, 4, 5, 6]) AS uids
    UNION ALL
    SELECT
        toInt32(3) AS tag_value,
        arrayToBitmap([5, 7]) AS uids
    UNION ALL
    SELECT
        toInt32(4) AS tag_value,
        arrayToBitmap([7]) AS uids
)

结果：

┌─res─────────┐
│ [3,4,4,3,3] │
└─────────────┘

BitmapMultiExtract

依据用户指定的一组计算表达式，每组执行相应的bitmap运算，返回每组最终bitmap。
语法：

BitmapMultiExtract(expr1, expr2, expr3,...)(idx_column, bitmap_column)

参数

• expr - 使用数字或字符串表示的与(&)、或(|)、差(~)运算，&表示bitmap交集，|表示bitmap并集，~表示bitmap差集，该函数支持多个表达式。
• idx_column - 用于标记 bitmap的数据列，可以是整数列(通常为 Int16/32/64类型)，或者字符串列。
• bitmap_column - BitMap64 数据列。

注1：不要求idx_column数据和bitmap_column数据一一对应，如果idx_column存在重复数据，则值相同的多行 bitmap 会先进行并集运算，合并为一个唯一的 bitmap 参与计算。
注2：当idx_column列类型位字符串时，不能包含如下保留字符：&, |, ~, ,, #, (, ), _和英文空格。
注3：支持结果复用。比如 expr1='a&b', expr2='(a&b)|c。那么可以简化 expr2 的写法为expr2='_1|c'。使用下划线+数字可以指定某个已经出现过的表达式，可以简化复杂表达式写法。

返回值

• BitMap64数组 - 每个表达式计算后的 bitmap，数组大小和表达式个数相等。

示例

SELECT BitmapMultiExtract('a')(tag_value, uids) AS res
FROM
(
    SELECT
        'a' AS tag_value,
        arrayToBitmap([1, 2, 3]) AS uids
)

┌─res───────┐
│ [{1,2,3}] │
└───────────┘

SELECT BitmapMultiExtract('1&2', '(1&2)|3', '_1|3', '((1&2)|3) ~ 4', '_2~4')(tag_value, uids) AS res
FROM
(
    SELECT
        toInt32(1) AS tag_value,
        arrayToBitmap([1, 2, 3, 4, 5]) AS uids
    UNION ALL
    SELECT
        toInt32(2) AS tag_value,
        arrayToBitmap([3, 4, 5, 6]) AS uids
    UNION ALL
    SELECT
        toInt32(3) AS tag_value,
        arrayToBitmap([5, 7]) AS uids
    UNION ALL
    SELECT
        toInt32(4) AS tag_value,
        arrayToBitmap([7]) AS uids
)

结果：

┌─res───────────────────────────────────────────┐
│ [{3,4,5},{3,4,5,7},{3,4,5,7},{3,4,5},{3,4,5}] │
└───────────────────────────────────────────────┘

BitmapMultiCountWithDate

依据用户指定的一组计算表达式，每组执行相应的bitmap运算，返回每组最终bitmap中元素个数。相比函数BitmapMultiCount多了一个日期表示维度。
语法：

BitmapMultiCountWithDate(expr1, expr2, expr3,...)(date_column, idx_column, bitmap_column)

参数

• expr - 使用数字或字符串表示的与(&)、或(|)、差(~)运算，&表示bitmap交集，|表示bitmap并集，~表示bitmap差集，该函数支持多个表达式，需要注意每个表达式由两部分组成：一部分是日期，一部分是标记，并使用下划线连接，示例为20240101_aaa&20240102_aaa。
• date_colulmn - 用于指定数据日期，需要时 Int64 类型表示的日期列，格式为 YYYYMMDD。
• idx_column - 用于标记 bitmap的数据列，可以是整数列(通常为 Int16/32/64类型)，或者字符串列。
• bitmap_column - BitMap64 数据列。

注1：不要求date_column+idx_column数据和bitmap_column数据一一对应，如果date_column+idx_column存在重复数据，则值相同的多行 bitmap 会先进行并集运算，合并为一个唯一的 bitmap 参与计算。
注2：当idx_column列类型位字符串时，不能包含如下保留字符：&, |, ~, ,, #, (, ), _和英文空格。
注3：支持结果复用。比如 expr1='a&b', expr2='(a&b)|c。那么可以简化 expr2 的写法为expr2='_1|c'。使用下划线+数字可以指定某个已经出现过的表达式，可以简化复杂表达式写法。

返回值

• UInt64数组 - 每个表达式计算后的 bitmap 中元素个数。数组大小和表达式个数相等。

示例

SELECT BitmapMultiCountWithDate('20240102_a~20240101_a', '20240101_a&20240102_a')(toInt64(toYYYYMMDD(date)), tag_value, uids) AS res
FROM
(
    SELECT
        'a' AS tag_value,
        '2024-01-01' AS date,
        arrayToBitmap([1, 2, 3]) AS uids
    UNION ALL
    SELECT
        'a' AS tag_value,
        '2024-01-02' AS date,
        arrayToBitmap([2, 3, 4, 5, 6]) AS uids
)

┌─res───┐
│ [3,2] │
└───────┘

SELECT BitmapMultiCountWithDate('20240101_1 & 20240102_2', '_1 | 20240101_3', '_2 ~ 20240101_4')(toInt64(toYYYYMMDD(date)), tag_value, uids) AS res
FROM
(
    SELECT
        toInt32(1) AS tag_value,
        '2024-01-01' AS date,
        arrayToBitmap([1, 2, 3, 4, 5]) AS uids
    UNION ALL
    SELECT
        toInt32(2) AS tag_value,
        '2024-01-02' AS date,
        arrayToBitmap([3, 4, 5, 6]) AS uids
    UNION ALL
    SELECT
        toInt32(3) AS tag_value,
        '2024-01-01' AS date,
        arrayToBitmap([5, 7]) AS uids
    UNION ALL
    SELECT
        toInt32(4) AS tag_value,
        '2024-01-01' AS date,
        arrayToBitmap([7]) AS uids
)

结果：

┌─res─────┐
│ [3,4,3] │
└─────────┘

BitmapMultiExtractWithDate

依据用户指定的一组计算表达式，每组执行相应的bitmap运算，返回每组最终bitmap。相比函数BitmapMultiExtract多了一个日期表示维度。
语法：

BitmapMultiExtractWithDate(expr1, expr2, expr3,...)(date_column, idx_column, bitmap_column)

参数

• expr - 使用数字或字符串表示的与(&)、或(|)、差(~)运算，&表示bitmap交集，|表示bitmap并集，~表示bitmap差集，该函数支持多个表达式，需要注意每个表达式由两部分组成：一部分是日期，一部分是标记，并使用下划线连接，示例为20240101_aaa&20240102_aaa。
• date_colulmn - 用于指定数据日期，需要时 Int64 类型表示的日期列，格式为 YYYYMMDD。
• idx_column - 用于标记 bitmap的数据列，可以是整数列(通常为 Int16/32/64类型)，或者字符串列。
• bitmap_column - BitMap64 数据列。

注1：不要求date_column+idx_column数据和bitmap_column数据一一对应，如果date_column+idx_column存在重复数据，则值相同的多行 bitmap 会先进行并集运算，合并为一个唯一的 bitmap 参与计算。
注2：当idx_column列类型位字符串时，不能包含如下保留字符：&, |, ~, ,, #, (, ), _和英文空格。
注3：支持结果复用。比如 expr1='a&b', expr2='(a&b)|c。那么可以简化 expr2 的写法为expr2='_1|c'。使用下划线+数字可以指定某个已经出现过的表达式，可以简化复杂表达式写法。

返回值

• BitMap64数组 - 每个表达式计算后的 bitmap，数组大小和表达式个数相等。

示例

SELECT BitmapMultiExtractWithDate('20240102_a~20240101_a', '20240101_a&20240102_a')(toInt64(toYYYYMMDD(date)), tag_value, uids) AS res
FROM
(
    SELECT
        'a' AS tag_value,
        '2024-01-01' AS date,
        arrayToBitmap([1, 2, 3]) AS uids
    UNION ALL
    SELECT
        'a' AS tag_value,
        '2024-01-02' AS date,
        arrayToBitmap([2, 3, 4, 5, 6]) AS uids
)

┌─res─────────────┐
│ [{4,5,6},{2,3}] │
└─────────────────┘

SELECT BitmapMultiExtractWithDate('20240101_1 & 20240102_2', '_1 | 20240101_3', '_2 ~ 20240101_4')(toInt64(toYYYYMMDD(date)), tag_value, uids) AS res
FROM
(
    SELECT
        toInt32(1) AS tag_value,
        '2024-01-01' AS date,
        arrayToBitmap([1, 2, 3, 4, 5]) AS uids
    UNION ALL
    SELECT
        toInt32(2) AS tag_value,
        '2024-01-02' AS date,
        arrayToBitmap([3, 4, 5, 6]) AS uids
    UNION ALL
    SELECT
        toInt32(3) AS tag_value,
        '2024-01-01' AS date,
        arrayToBitmap([5, 7]) AS uids
    UNION ALL
    SELECT
        toInt32(4) AS tag_value,
        '2024-01-01' AS date,
        arrayToBitmap([7]) AS uids
)

结果：

┌─res─────────────────────────┐
│ [{3,4,5},{3,4,5,7},{3,4,5}] │
└─────────────────────────────┘

其他函数与操作接口

BitEngine场景编解码函数