NumericIndexedVector 函数

NumericIndexedVector 是一种抽象数据结构，用于封装向量，并支持向量聚合和按元素操作。其存储方式为 Bit-Sliced Index。有关其理论基础和适用场景，请参阅论文 Large-Scale Metric Computation in Online Controlled Experiment Platform。

BSI

在 BSI (Bit-Sliced Index) 存储方法中，数据会以 Bit-Sliced Index 的形式存储，再使用 Roaring Bitmap 进行压缩。聚合操作和按元素操作都直接作用于压缩后的数据，因此可以显著提升存储和查询效率。

一个向量包含索引及其对应的值。以下是在 BSI 存储模式下，这种数据结构的一些特性和约束：

索引类型只能是 UInt8、UInt16 或 UInt32 之一。注意： 考虑到 Roaring Bitmap 在 64 位实现下的性能，BSI 格式不支持 UInt64/Int64。
值类型可以是 Int8、Int16、Int32、Int64、UInt8、UInt16、UInt32、UInt64、Float32 或 Float64 之一。注意： 值类型不会自动扩展。例如，如果使用 UInt8 作为值类型，任何超过 UInt8 容量的求和都会发生溢出，而不会自动提升为更高类型；同样，整数运算的结果仍然是整数 (例如，除法不会自动转换为浮点结果) 。因此，提前规划和设计值类型非常重要。在实际场景中，通常会使用浮点类型 (Float32/Float64) 。
只有索引类型和值类型都相同的两个向量才能进行运算。
底层存储采用 Bit-Sliced Index，索引由 bitmap 存储，具体实现使用的是 Roaring Bitmap。最佳实践是尽可能将索引集中到少数几个 Roaring Bitmap 容器中，以最大化压缩率和查询性能。
Bit-Sliced Index 机制会将值转换为二进制。对于浮点类型，转换时会使用定点表示，因此可能带来精度损失。精度可以通过自定义小数部分所使用的位数进行调整，默认值为 24 位，对大多数场景已足够。你可以在使用带 -State 的聚合函数 groupNumericIndexedVector 构造 NumericIndexedVector 时，自定义整数位数和小数位数。
索引有三种情况：非零值、零值和不存在。在 NumericIndexedVector 中，只有非零值和零值会被存储。此外，在两个 NumericIndexedVector 之间进行按元素运算时，不存在的索引值会被视为 0。在除法场景下，如果除数为零，结果为零。

创建 numericIndexedVector 对象

创建这种结构有两种方式：一种是将聚合函数 groupNumericIndexedVector 与 -State 结合使用。你还可以添加 -if 后缀以接受额外条件。该聚合函数只会处理满足该条件的行。另一种方式是使用 numericIndexedVectorBuild 基于 map 构建。 groupNumericIndexedVectorState 函数允许通过参数自定义整数位和小数位的位数，而 numericIndexedVectorBuild 不支持。

groupNumericIndexedVector

从两个数据列构造 NumericIndexedVector，并以 Float64 类型返回所有值之和。若添加 State 后缀，则返回一个 NumericIndexedVector 对象。

语法

groupNumericIndexedVectorState(col1, col2)
groupNumericIndexedVectorState(type, integer_bit_num, fraction_bit_num)(col1, col2)

参数

type：String，可选。指定存储格式。目前仅支持 'BSI'。
integer_bit_num：UInt32，可选。仅在 'BSI' 存储格式下生效，表示整数部分使用的位数。当索引类型为整数类型时，默认值等于存储该索引所用的位数。例如，如果索引类型为 UInt16，则默认 integer_bit_num 为 16。对于 Float32 和 Float64 索引类型，integer_bit_num 的默认值为 40，因此可表示数据的整数部分范围为 [-2^39, 2^39 - 1]。其合法范围为 [0, 64]。
fraction_bit_num：UInt32，可选。仅在 'BSI' 存储格式下生效，表示小数部分使用的位数。当值类型为整数时，默认值为 0；当值类型为 Float32 或 Float64 时，默认值为 24。其合法范围为 [0, 24]。
此外还有一个约束：integer_bit_num + fraction_bit_num 的合法范围为 [0, 64]。
col1：索引列。支持的类型：UInt8/UInt16/UInt32/Int8/Int16/Int32。
col2：值列。支持的类型：Int8/Int16/Int32/Int64/UInt8/UInt16/UInt32/UInt64/Float32/Float64。

返回值

一个 Float64 值，表示所有值之和。

示例

测试数据：

UserID  PlayTime
1       10
2       20
3       30

查询与结果：

SELECT groupNumericIndexedVector(UserID, PlayTime) AS num FROM t;
┌

numericIndexedVectorAllValueSum

在 v25.7.0 中引入

返回 numericIndexedVector 中所有值之和。

语法

numericIndexedVectorAllValueSum(v)

参数

v — numericIndexedVector

返回值

返回其总和。Float64

示例

使用示例

SELECT numericIndexedVectorAllValueSum(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res;

┌─res─┐
│  60 │
└─────┘

numericIndexedVectorBuild

引入版本：v25.7.0

从 Map 创建 NumericIndexedVector。Map 的键表示向量的索引，Map 的值表示向量的值。

语法

numericIndexedVectorBuild(map)

参数

map — 从索引到值的映射。Map

返回值

返回一个 NumericIndexedVector 对象。AggregateFunction

示例

使用示例

-- A NumericIndexedVector is a binary value, so it is shown with `hex`.
SELECT
    hex(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res,
    toTypeName(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS type;

┌─res────────────────────────────────────────────────────────────────┬─type───────────────────────────────────────────────────────┐
│ 080000000000000001010000020103000002020300000201030000020203010101 │ AggregateFunction(groupNumericIndexedVector, UInt8, UInt8) │
└────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘

numericIndexedVectorCardinality

引入版本：v25.7.0

返回 numericIndexedVector 的基数 (即唯一索引的数量) 。

语法

numericIndexedVectorCardinality(v)

参数

v — numericIndexedVector

返回值

返回唯一索引的个数。UInt64

示例

使用示例

SELECT numericIndexedVectorCardinality(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res;

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

numericIndexedVectorGetValue

引入版本：v25.7.0

从 numericIndexedVector 中获取与指定索引对应的值。

语法

numericIndexedVectorGetValue(v, i)

参数

v — numericIndexedVector
i — 要获取其值的索引。 (U)Int*

返回值

一个数值，其类型与 NumericIndexedVector 中值的类型相同。(U)Int* 或 Float*

示例

使用示例

SELECT numericIndexedVectorGetValue(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30])), 3) AS res;

┌─res─┐
│  30 │
└─────┘

numericIndexedVectorPointwiseAdd

引入版本：v25.7.0

对一个 numericIndexedVector 与另一个 numericIndexedVector 或数值常量进行按元素相加。

语法

numericIndexedVectorPointwiseAdd(v1, v2)

参数

v1 — numericIndexedVector
v2 — 数值常量或 numericIndexedVector 对象。(U)Int* 或 Float* 或 numericIndexedVector

返回值

返回一个新的 numericIndexedVector 对象。numericIndexedVector

示例

用法示例

WITH
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toInt32(x), [10, 20, 30]))) AS vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toInt32(x), [10, 20, 30]))) AS vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseAdd(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseAdd(vec1, 2)) AS res2;

┌─res1──────────────────┬─res2─────────────┐
│ {1:10,2:30,3:50,4:30} │ {1:12,2:22,3:32} │
└───────────────────────┴──────────────────┘

numericIndexedVectorPointwiseDivide

引入版本：v25.7.0

对 numericIndexedVector 与另一个 numericIndexedVector 或数值常量执行按元素除法运算。

语法

numericIndexedVectorPointwiseDivide(v1, v2)

参数

v1 — numericIndexedVector
v2 — 数值常量或一个 numericIndexedVector 对象。(U)Int* 或 Float* 或 numericIndexedVector

返回值

返回一个新的 numericIndexedVector 对象。numericIndexedVector

示例

使用示例

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 30]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [10, 20, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseDivide(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseDivide(vec1, 2)) AS res2;

┌─res1────────────────┬─res2────────────┐
│ {1:0,2:2,3:1.5,4:0} │ {1:5,2:10,3:15} │
└─────────────────────┴─────────────────┘

numericIndexedVectorPointwiseEqual

引入版本：v25.7.0

对一个 numericIndexedVector 与另一个 numericIndexedVector 或数值常量按元素进行比较。结果是一个 numericIndexedVector，包含值相等的索引位置，且对应的所有值都设为 1。

语法

numericIndexedVectorPointwiseEqual(v1, v2)

参数

v1 — numericIndexedVector
v2 — 数值常量或 numericIndexedVector 对象。(U)Int* 或 Float* 或 numericIndexedVector

返回值

返回一个新的 numericIndexedVector 对象。

示例

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 30]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [20, 20, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseEqual(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseEqual(vec1, 20)) AS res2;

┌─res1──┬─res2──┐
│ {2:1} │ {2:1} │
└───────┴───────┘

numericIndexedVectorPointwiseGreater

引入于：v25.7.0

对一个 numericIndexedVector 与另一个 numericIndexedVector 或数值常量按元素进行比较。结果是一个 numericIndexedVector，其中包含第一个向量的值大于第二个向量值的索引，且所有对应的值均设为 1。

语法

numericIndexedVectorPointwiseGreater(v1, v2)

参数

v1 — numericIndexedVector
v2 — 数值常量，或 numericIndexedVector 对象。(U)Int* 或 Float* 或 numericIndexedVector

返回值

返回一个新的 numericIndexedVector 对象。numericIndexedVector

示例

使用示例

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 50]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [20, 40, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseGreater(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseGreater(vec1, 20)) AS res2;

┌─res1──────┬─res2──┐
│ {1:1,3:1} │ {3:1} │
└───────────┴───────┘

numericIndexedVectorPointwiseGreaterEqual

引入版本：v25.7.0

对一个 numericIndexedVector 与另一个 numericIndexedVector 或数值常量进行按元素比较。结果是一个 numericIndexedVector，包含第一个向量中值大于或等于第二个向量对应值的索引，且所有对应值均设为 1。

语法

numericIndexedVectorPointwiseGreaterEqual(v1, v2)

参数

v1 — numericIndexedVector
v2 — 数值常量或 numericIndexedVector 对象。(U)Int* 或 Float* 或 numericIndexedVector

返回值

返回一个新的 numericIndexedVector 对象。numericIndexedVector

示例

使用示例

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 50]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [20, 40, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseGreaterEqual(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseGreaterEqual(vec1, 20)) AS res2;

┌─res1──────────┬─res2──────┐
│ {1:1,2:1,3:1} │ {2:1,3:1} │
└───────────────┴───────────┘

numericIndexedVectorPointwiseLess

引入版本：v25.7.0

对一个 numericIndexedVector 与另一个 numericIndexedVector 或数值常量按元素进行比较。结果为一个 numericIndexedVector，其中包含第一个向量的值小于第二个向量的值的索引，且所有对应的值都设为 1。

语法

numericIndexedVectorPointwiseLess(v1, v2)

参数

v1 — numericIndexedVector
v2 — 数值常量或 numericIndexedVector 对象。(U)Int* 或 Float* 或 numericIndexedVector

返回值

返回一个新的 numericIndexedVector 对象。numericIndexedVector

示例

使用示例

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 30]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [20, 40, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseLess(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseLess(vec1, 20)) AS res2;

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

numericIndexedVectorPointwiseLessEqual

引入版本：v25.7.0

对 numericIndexedVector 与另一个 numericIndexedVector 或数值常量进行按元素比较。结果为一个 numericIndexedVector，其中包含第一个向量中值小于或等于第二个向量对应值的位置索引，且所有对应值均设为 1。

语法

numericIndexedVectorPointwiseLessEqual(v1, v2)

参数

v1 — numericIndexedVector
v2 — (U)Int* 或 Float* 类型的数值常量，或 numericIndexedVector 对象

返回值

返回一个新的 numericIndexedVector 对象。

示例

用法示例

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 30]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [20, 40, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseLessEqual(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseLessEqual(vec1, 20)) AS res2;

┌─res1──────────┬─res2──────┐
│ {2:1,3:1,4:1} │ {1:1,2:1} │
└───────────────┴───────────┘

numericIndexedVectorPointwiseMultiply

引入版本：v25.7.0

对一个 numericIndexedVector 与另一个 numericIndexedVector 或数值常量按元素执行乘法运算。

语法

numericIndexedVectorPointwiseMultiply(v1, v2)

参数

v1 — numericIndexedVector
v2 — 数值常量或 numericIndexedVector 对象。(U)Int* 或 Float* 或 numericIndexedVector

返回值

返回新的 numericIndexedVector 对象。numericIndexedVector

示例

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toInt32(x), [10, 20, 30]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toInt32(x), [10, 20, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseMultiply(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseMultiply(vec1, 2)) AS res2;

┌─res1──────────────────┬─res2─────────────┐
│ {1:0,2:200,3:600,4:0} │ {1:20,2:40,3:60} │
└───────────────────────┴──────────────────┘

numericIndexedVectorPointwiseNotEqual

引入版本：v25.7.0

对一个 numericIndexedVector 与另一个 numericIndexedVector 或数值常量进行按元素比较。结果是一个 numericIndexedVector，其中包含值不相等的位置索引，且所有对应的值均设为 1。

语法

numericIndexedVectorPointwiseNotEqual(v1, v2)

参数

v1 — numericIndexedVector
v2 — 数值常量或 numericIndexedVector 对象。(U)Int* 或 Float* 或 numericIndexedVector

返回值

返回一个新的 numericIndexedVector 对象。numericIndexedVector

示例

使用示例

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 30]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [20, 20, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseNotEqual(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseNotEqual(vec1, 20)) AS res2;

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

numericIndexedVectorPointwiseSubtract

引入版本：v25.7.0

对 numericIndexedVector 与另一个 numericIndexedVector 或数值常量进行按元素相减。

语法

numericIndexedVectorPointwiseSubtract(v1, v2)

参数

v1 — numericIndexedVector
v2 — 数值常量或 numericIndexedVector 对象。(U)Int* 或 Float* 或 numericIndexedVector

返回值

返回一个新的 numericIndexedVector 对象。

示例

用法示例

WITH
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toInt32(x), [10, 20, 30]))) AS vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toInt32(x), [10, 20, 30]))) AS vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseSubtract(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseSubtract(vec1, 2)) AS res2;

┌─res1───────────────────┬─res2────────────┐
│ {1:10,2:10,3:10,4:-30} │ {1:8,2:18,3:28} │
└────────────────────────┴─────────────────┘

numericIndexedVectorShortDebugString

自 v25.7.0 起引入

以 JSON 格式返回 numericIndexedVector 的内部信息。此函数主要用于调试。

语法

numericIndexedVectorShortDebugString(v)

参数

v — numericIndexedVector

返回值

返回包含调试信息的 JSON 字符串。String

示例

使用示例

SELECT numericIndexedVectorShortDebugString(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res FORMAT Vertical;

Row 1:
──────
res: {"vector_type":"BSI","index_type":"char8_t","value_type":"char8_t","integer_bit_num":8,"fraction_bit_num":0,"zero_indexes_info":{"cardinality":0},"non_zero_indexes_info":{"total_cardinality":3,"all_value_sum":60,"number_of_bitmaps":8,"bitmap_info":{"cardinality":{"0":0,"1":2,"2":2,"3":2,"4":2,"5":0,"6":0,"7":0}}}}

numericIndexedVectorToMap

引入版本：v25.7.0

将 numericIndexedVector 转换为映射 (Map) 。

语法

numericIndexedVectorToMap(v)

参数

v — numericIndexedVector

返回值

返回包含索引和值对的映射。Map

示例

使用示例

SELECT numericIndexedVectorToMap(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res;

┌─res──────────────┐
│ {1:10,2:20,3:30} │
└──────────────────┘